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ABOUT THIS BOOK... 

Ihis book is intended to replace PDR3061, The MIDAS Reference Guide . 
Its emfiiasis is on acquainting the first-time or relatively 
new-to-MIDAS user with the basic concepts of MID?iS. Kjwever, the needs 
of the experienced or long-time MIDAS user have not been overlooked. 
Since it was not possible to satisfy everyone's particular needs at 
this first writing, anyone with useful ideas and suggestions regarding 
the improvement of the book should not hesitate to contact the author. 

all ni-irMi+- i.ii 1 1 V\a r^nntzT AaraA fnr i nr-z-iKrv-vr-al- 4 r>n Itrl-n ■fnt-iiro ro^/l cinnc rtf 

this book. Ihis is your user's guide and only you know v*iat else you'd 
like to see in it. 



HOW TO USE THIS BOOK 

J^rt I introduces MIDAS and briefly describes its major functions and 
features. Users needing additional background on terminology used here 
should see impend ix B. 

Part II covers MIDAS file creation and the role of CREATK in setting up 
a MIDAS file template. MIDAS file deletion is also covered here. 

Part III covers all the currently available language interfaces to 
MIDAS. It describes how to access a MIDAS file in CCBOL, FORTRAN, 
BASIC/VM and so forth. 

Part IV talks about the basic MIDAS file maintenance tasks that can be 
done by the user. It also covers MIDAS system maintenance and 
initialization, vAiich is usually handled by the System Administrator, 
or vdioever is in charge of MIDAS at a particular site. 

Part V deals with the more esoteric aspects of MIDAS, most of v^iich 
will mean little to new users at first. Veteran MIDAS users may find 
this material helpful in tuning MIDAS performance. Programmers vho 
like to do things for themselves will find the information about the 
offline MIDAS routines useful in writing certain applications. 

Ihe collection of appendices includes a complete set of MIDAS run-time 
error message codes and explanations, a description of how MIDAS fits 
in with the rest of the PRIME file system, a summary of obsolete 
routines, and a summary of the changes that have occurred to MIDAS at 
this revision (17.6). 
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Oonventions 

The following conventions are used throughout this book, and should 
reviewed before reading further: 



be 



Braces { } 

Brackets [ ] 
Underlining 

(CR) 



Used to show a series of arguments, parameters or 
keywords, at least one of vhidh must be chosen, 
unless the braces are themselves enclosed by 
brackets. 

Used to indicate that the enclosed parameters, 
arguments or keywords are optional. 

Generally used in examples to distinguish user 
input from system output. May also be used to 
indicate the minimun abbreviation of certain 
options, parameters, command words or responses. 

this symbol indicates a single carriage return, 
that is, a single hitting of the RETURN key on most 
terminals. It is used in examples to show that the 
user typed a carriage return, and nothing else in 
response to some MIDAS utility prompt. 

Note 



It is assumed that users already know that any command or 
response entered, either to reiMOS or to any MIDAS utility, 
must be terminated by a carriage return, v\*iich causes the 
information typed by the user to be transmitted. 
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SECTION 1 
INTRODUCTIOJ TO MIDAS 



INTRODUCTION 

MIDAS, the Multiple Index Data A::cess Syston, is a collection of 

aukjl.(juuj.iica aiKi xhuclq^uxvc uuxx j. l-lco l^icii. ciicu^xc uiic oxiiif-L^ 

construction, access and maintenance of keyed data files. Because of 
their structure, information can be rapidly retrieved frcm MIDAS files 
through high-level languages like FORTRAN, CCBOL and BASIC/VM. Chce 
the overall shape (structure) of the MIDAS file is established, data 
can be added to it on-line through interactive programs, or through 
application programs. Alternatively, by using MIDAS utilities, data in 
existing sequential (non-MIDAS) files can be added to MIDAS files. The 
process of building a MIDAS file is quite simple. MIDAS does most of 
the work; the user merely provides the information requested by the 
various MIDAS file-building programs. 



Vihen Tb Use MIDAS 

MIDAS file structure and access is key-oriented, making it easier for 

uSera \.0 iiiaiiiuaxii, upOauc anCi Lcuticvc j.iii.OLiiia<.xuii Sukjicu xH ilX>i.ii xax'^^e 

and small files. Although MIDAS is indeed a useful tool in many 
applications, it is not always the h>est answer. VJnile this book cannot 
address every possible situation v*iere MIDAS might be under 
consideration, it can offer a few basic guidelines. Briefly, MIDAS 
should be used v*ien: 

• A large file of information is to be accessed by one or more 
keys. Fbr example, a customer master file may be accessed by 
account nunber or by customer name. 

• A file needs to be accessed and updated on-line by several users 
simultaneously. 

• Various factors like nunbers of files per application, nunber of 
keys per file, nunber of files accessed per program, security 
requiranents and necessary recovery features indicate that I^4S 
is not a preferred solution. Ihese factors should be discussed 
with a systems analyst v*ien determining v*iich of Prime's data 
management products are most suited to your particular 
application. 
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Haw lb Access MIDAS 



MIDAS files are created and maintained by a collection of Prime 
supplied utilities and subroutines, all of v*iich are later described in 
detail. MIDAS files can be accessed through these Prime languages: 

BASIC/ VM 
CCBOL 

FORTRAH/FC«TRAN 77 
RPGII 

PI/I 
PMA 

Ordinarily, a MIDAS file is set up for use with a particular language 
interface; however, it is possible to access a MIDAS file with any of 
these Prime high-level languages. 



WHAT A MIDAS FILE LOOKS LIKE 

Although the user need not know all the details of MIDAS file 
structure, there are scxne basic terms and concepts viiich are important. 
The remainder of this book assunes that the reader is familiar with 
certain fundamental information, most of v*iich is dealt with in this 
section. Other details are covered in Appendix B, as indicated. 

Sane Basic Tterms and Oancepts 

A typical data file is composed of records , viiich are divided into one 
or more related fields . Each field in a record is a piece of data, 
like a last name, age or phone number, v*iich describes or pertains to 
an individual event, person, canpany, and so forth. Each record in the 
file has the same field layout; for example, each record has a last 
name, age, and phone nunber field. The important thing is that the 
actual contents of each field (called the field value ) will generally 
differ from record to record. Ihus, at least one field in each record 
will have a unique value, thereby distinguishing each record from all 
other file records. 

Some file records contain tWD kinds of fields: those v*iich identify 
the record and those vAiich describe the record. The fields which 
identify a record are usually called key-fields or keys . Such fields 
are distinguished frcm other fields in the record v*iich simply contain 
descriptive data, or "detail" information. Files with key fields are 
called "keyed" files. Detail information tends to be less unique or 
less used in everyday applications. 

Keys are most often used for file searches because they readily 
identify a particular record. However, keys usually mean additional 
file overhead, that is, they require more storage. Keyed fields 
therefore should be used sparingly and chosen carefully. They should 
be fields v*iich users are most likely to search on. 
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An Illustration : A keyed file, for example, might be an EMPLOYEE file 
\*iich may contain many records, one for each employee in a canpany. 
Each data record contains information on each employee, and may be 
divided into several fields, such as SOCIAL-SECURITY-NO, LAST-NAME, 
FIRST-NAME, PAY-RATE, and EMPLOYEE-NO. (See Figure 1-1.) 

Certain fields, like SOCIAL-SECURITY-NO, LAST-NAME, and PAY-RATE, are 
designated as file search keys. 

A particular record is retrieved by searching on one of these unique 
key values. For example, to fetch the enployee OGLETHORPE'S record in 
the EMPLOYEE file (refer to Figure 1-1), you could use the LAST-NAME 
key value of "OGLETHORPE", or the SOCIAL-SECURITY-NO key value of 
"313-09-8666". 

Types of Keys ; There are two kinds of keys: primary and secondary . A 
primary key must have a unique value for each record in the data file, 
with only one primary key field per record. A secondary key is not 
required to have a unique value in every record, and there may be as 
many as 17 secondary keys per MIDAS file record. Keys may be one of 
eleven data types. For complete details, see Section 2. 

In the EMPLOYEE file, the SOCIAL-SECURITY-NO key could be the primary 
key because it guarantees a unique value for every onployee in the 
i-j-j-B » ihe OiJisr rkSysu j.iej.ds m the record, like PAY— RATE and 
LAST-NAME, are secondary keys and may or may not have unique values. 



MIDAS File Structure 

The concepts just described in the sample data file, EMPLOYEE, apply to 
MIDAS files as well. A MIDAS file is a type of keyed file known as a 
keyed-index file. A keyed-index file consists of at least tWD parts: 
a kei^ data file and an irx3ex file. 

The index file, called an index siijfile in MIDAS, simply stores all the 
key values that appear in the MIDAS data file. Because there may be 
more than one key field in a data record, MIDAS creates one index 
subfile for each key. Because of this profusion of subfiles, a MIDAS 
file is also called a segment directory . A segment directory is 
liiysically made up of one or more segment subfiles, but logically, the 
segment directory is one file with a single file name. In a MIDAS 
file, one of these segment subfiles is the data subfile, the other, the 
primary index subfile. See Figure 1-2 for a representation of MIDAS 
file structure. Ebr a more complete description of MIDAS structure, as 
well as other Prime file structure concepts, refer to Appendix B. 
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KEY 



KEY-FIELD 



FIELD 

FIELD-NAME 

RECORD 1 
RECORD 2 

RECORDS 
RECORD 4 



RECORD n-1 



RECORD n 



PRIMARY 
KEY 


SECONDARY 
KEY 1 


SECONDARY 
KEYn 


DATA ••• 


• •• DATA 


KEY-FIELD-VALUE 


KEY-FIELD VALUE 


KEY FIELD-VALUE 


FIELD VALUE 


FIELD-VALUE 



TYPICAL DATA RECORD 



PRIMARY KEY 


SECONDARY 
KEY1 


SECONDARY 
KEY 2 


DATA-FIELD 


SOCIAL-SECURITY 
NO. 


LAST-NAME 


PAYRATE 


FIRST-NAME 


313-09-8666 


OGLETHORPE 


301.25 


GREGORY 


132-34-6789 


WONG 


348.00 


JANE 


002-49-6222 


CHERRY 


380.00 


DAVE 


134-01-9999 


LARSON 


348.00 


SUSAN 









Figure 1-1. Ehiployee Data File With Three Keys 
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Index Subfile Oontents ; Index subfiles store key field values that 
appear in the records of a data file and are used by MIEAS v*ien looking 
for a particular key value during a file search. Because there are two 
types of keys, there are tvo types of index subfiles: a primary index 
sifcfile and a secondary index subfile . Every MIEftS file has a primary 
index subfile, and, depending on tHe" nunber of secondary keys, an 
equivalent nunber of secondary index subfiles. 

Assuming that every record in the data file has at least one key field, 

, sg _ J.. _„.«^j ,»^,j, vaj-Og/ , ujc ^fniuaLy ±r£icx. E>uDClJ.e EOf tiiat 

MIDAS file would list all of these values; in this case, the primary 
index subfile wuld have one entry per data file record. Depending on 
how many data records have a field entry for the correspondirq 
secondary key, and on the interface used to add the data records, the 
nunber of secondary index entries will vary. This is described in more 
detail in the language interface sections. 

Index Subfile Ehtries ; Each entry in an index subfile consists of a 
key value from a particular record in the data file plus a pointer to 
that record. A pointer is a three-word address that tells MIEftS v*iere 
to find the associated record. Ihe entries in an index subfile are 
stored in a B-tree, a special type of binary tree. The data file 
records are not stored in the same order as the index entries, but that 
doesn't matter because each index entry always points to the right data 
record. The index entries are always stored in an orderly fashion; 
the entry with the lowest value is tfie first entry in the index, 
followed by entries of increasingly greater value. 

The '"Janplate" Concept 

Although the exact nunber of files and subfiles varies, there are 
always tW3 logical parts to a MIEftS file: the various index subfiles, 
and the data file , v^^iich contains the information to be accessed. 
Collectively, these two parts are called a tanplate. 

The data file, also called a data subfile , consists of records v*iich 
can be referenced throi^h the primary index subfile by specifying a 
primary key value. Each entry in the data subfile is "pointed to" by 
its unique primary key entry in the primary index subfile. 

»hat is a Tsmplate? ; A file template is a structural definition of a 
MIEftS file; it consists of all the index subfiles needed for key value 
storage, plus a few other subfiles and pointers. It is essentially an 
initialized (unpopulated = empty) MIEftS file. 
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KEYS 

IN 

PRIMARY 

INDEX 

SUBFILE 



KEYS 

IN 

SECONDARY 

INDEX 

SUBFILE 

01 



KEYS 

IN 

SECONDARY 

INDEX 

SUBFILE 

02 




NOTE 

ARROWS ARE POINTERS TO RECORDS IN 
DATA SUBFILE. EACH ENTRY IN THE 
INDEX SUBFILE HAS A POINTER TO THE 
RECORD IN THE DATA SUBFILE THAT HAS 
A MATCHING KEY FIELD. FOR EXAMPLE. 
THE RECORD CONTAINING INFO ON JANE 
WONG CAN BE REFERENCED THROUGH THE 
ENTRIES IN THE INDEX SUBFILES THAT 
MATCH. AS SHOWN IN THE DIAGRAM. 



132-34.6789 



002-99-6222 






RECORD n-1 



OGLETHORPE 



WONG 



301 .26 



348.00 



380.00 



GREGORY 



RECORDS 



DATA SUBFILE 



SECONDARY INDEX SUBFILE 02 



Figure 1-2. Logical View of a MIDAS File 
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A template's primary function is to accurately define the strircture and 
properties of a MIDAS data file. MIDAS utilities and access routines 
require a template in order to access the information in a data file. 
The "definition" of a MIDAS file includes a description of all the data 
file's key types and lengths, and the data file record length. 

Setting Up A Template ; The MIDAS utility CREATK sets up a MIDAS file 
template using interactive dialog. CREATK asks for information about 
the tonplate you intend to build. Basically, CREATK requires only the 
key types and sizes, plus the length of the data record, to be 
specified. Based on this information, CREATK sets up the appropriate 
index subfile skeletons and pointers required by MIDAS. (More on 
CREATK in Section 2.) 



FRCM THE USER'S VIEWPOINT 

Fran the user's point of view, the first step in setting up a MIDAS 
file is to create a template vdth CREATK. Ihe second step is to 
populate, or add data to the file, building the data subfile mentioned 
earlier. The data subfile can be "built" in several ways, all of vhich 
are discussed in Section 3. Qice the file is populated you can access 
individual data records by primary and/or secondary key. Below are 
some descriptions of v*iat happens during record addition and record 
access . 



What Happens t\hen You A3d A Record 

Records are added to a MIDAS data file by primary key; the primary key 
entry for the record is added to the primary index at this time. Vten 
you add a record to a MIDAS file in any of the language interfaces, the 
new record is written to the end of the data file. If desired, the 
user may then add the appropriate secondary key value to each of the 
secondary index subfiles for that file so the record can be referenced 
by one or more secondary keys. Keep in mind that there are no pointers 
from the data subfile to the index subfiles; pointers are maintained 
in one direction only: from the index subfile entries to the data 
subfile records. Cnly the pointer frc«n the primary index subfile to 
the data subfile record is created upon record addition; secondary 
index subfile pointers must be added individually in sane of the 
language interfaces. In others, the secondary index subfile entries 
are automatically added when the record (and primary index entry) is 
added. 



What Happens When You Delete A Record 

A record is "deleted" from a MIDAS file by deleting its primary key, 
Chce a primary index entry (key value) is deleted, there is no vay to 
get to the data subfile record it used to reference. The record in the 
data subfile is then marked as deleted, and the area is not reused 
until MPACK is run. MPACK is a special MIDAS utility that reclaims 
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"deleted" areas in the data subfile and in the various index subfiles 
for future use. 

V4ien a record is deleted by primary key, the corresponding secondary 
index entries for this record are marked for deletion but are not 
deleted until a user attonpts to use than to reference this record. 
Since the pointer in the index entry references a deleted record, the 
secondary index entry is then removed from the index. Hawever, 
secondary index entries can be deleted independently of the primary 
index entry in most language interfaces in v*iich case the index entry 
space is automatically reclaimed (that is, MIDAS could use it for 
another entry) . 

Deleting Index Subfile ; The entire contents and template description 
of a secondary index subfile can be deleted with the KIDDEL utility. 
KIDDEL asks for the numbers of the index subfiles to be deleted. The 
entire file can be deleted by specifying ALL. HDwever, you cannot 
delete just the primary index subfile, as this would render the file 
inaccessible. See Section 4 for further details on the KIDDEL utility. 

MIDAS File Access Methods 

There are two ways to retrieve information fran a MIDAS file: the 
"keyed-index" method and the "direct access" method. A MIDAS file 
template can be set up for keyed-index access only, or it can be set up 
to use both methods. 

Keyed-Index Access ; From the user's viewpoint, keyed-index access 
involves giving MIDAS a primary or secondary key value and waiting for 
MIDAS to return the appropriate record. MIDAS does keyed-index file 
searches by looking through a list of index subfile entries for a match 
on the user-supplied key value. Chce a match is found, the 
corresponding record in the data subfile is located by following the 
pointer frcm the index subfile to the data sitifile. Sequential 
searches are also possible by performing a "get next record" operation, 
v*iich tells MIDAS to return the next record entry in the data subfile. 
Partial searches can also be done by using a prefix of the full key 
value. 



Direct Access: Direct access is based on record nunbers. Each record 



in the data subfile is given a unique number, lb access a particular 
record, the user simply gives MIDAS a record number. Although the user 
must keep track of record numbers, this method can be faster than 
keyed-index access because there is less searching involved. Direct 
access files in COBOL require that the primary key be the record 
nunber. FORTRAN, however, does not levy this restriction; thus, 
direct access files in FTO can be accessed either by record nunber or 
by primary or secondary key. Ebr direct access files with primary and 
secondary keys in addition to record nunbers, the keyed-index access 
method can be used to retrieve information by key value. This means 
that the keyed-index method can be used on files of either type of 
template, vAiile direct access only wDrks on templates set up for direct 
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access. Direct access is supported only by the CCBOL, FORTRAN and 
RPGII MIDAS interfaces. 



THE MIDAS SYSTEM 

The MIDAS system consists of Prime-supplied interactive programs, 
called "utilities," and file access subroutines. The utilities are 

reSOOnsibl e for flip G*'e''l"i'^" - modi'f''<^a*"io" »'t1 ma 1 nl-onanoo . 1-Vio 

subroutines are used to add, delete, modify and access information in 
existing MIDAS files. 

MIDAS Utilities 

Ihe MIDAS utilities are directly accessible from PRIMOS command level. 
These utilities build and modify MIDAS file structure: 

• CREATK creates/modifies a MIDAS file. 

• KBUILD adds entries to a MIDAS data subfile and index subfiles 
from sequential disk files. 

• KIDDEL deletes a MIDAS file (partially or totally) . 

• MPACK restructures an overgrown or inefficient MIDAS file. 

A Mbrd on Utility Names ; Ebr those curious unbelievers, the MIDAS 
utility names do have some real meaning. CREATK is almost 
obvious — the "K" stands for "keyed" to distinguish it from the other 
PRIMOS level command CREATE, vi*iich creates ordinary files and 
directories, but not segment directories, vAiich is CREATK' s job. 
KBUILD builds "keyed" files; KIDDEL deletes (DEL) keys, indexes and 
data (K, I, D) ; MPACK "packs up," or recovers space in MIDAS files 
(M) . So, v*iile they may not seem totally consistent, the names do make 
sense. 

The MIDAS Life Cycle 

For those of you who find it easier to think of dry subjects like MIDAS 
in biological terms, the following paragraphs are presented for your 
enjoyment. 

Ihe four MIDAS utilities described briefly above are in charge of 
managing the "life cycle" of a MIDAS file. CREATK gives birth to a 
MIDAS file, defining its shape and general characteristics. Based on 
the user's specifications, it creates a skeleton for the file. CREATK 
also serves as a "monitor" for the MIDAS file during its lifetime, 
providing important information about its skeletal structure, and, to 
some degree, about its contents. In fact, CREATK can even make minor 
adjustments to the file's skeleton at the user's command, improving its 
useability. 
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All this is well and good but we have to get infonnation into the MIDAS 
file once we've defined its shape. The KBUILD utility does this by 
taking existing sequential (non-MIDAS) disk files with the infonnation 
we want to put into the MIDAS database, and putting it into the proper 
cubb^tioles in the MIDAS file superstructure. It puts key entries into 
the proper index subfiles and record entries into the data subfile. 

Sometimes a MIDAS file begins suffering from the common ailments 
associated with repeated use (and abuse) and must undergo corrective 
surgery. The utility that performs this service is MPACK. It can do 
anything from a major overhaul to a simple face-lift. Major overhauls 
usually involve recovering the space wasted by data subfile and 
secondary index entries marked for deletion, plus checking to see that 
all index entries are in the proper order and reporting than to the 
user if they aren't, and finally, reordering the data subfile entries 
so the file can be used more efficiently. Minor coanetic surgery 
involves unlocking records v*iich were locked by program failure or 
maybe by syst«n failure during file processing, or it might involve 
packing up an index subfile or tvo, again recovering space occupied by 
"deleted" index entries. 

At some point in the life cycle of a MIDAS file, surgery may no longer 
be a viable option. Clearly, a miracle is in order. Hbwever, there is 
no life-giving utility in MIDAS. Instead, the KIDDEL utility has the 
unique task of meting out several types of death sentences to a MIDAS 
file. If the user determines that the shape of the MIDAS file can be 
used again in v*K>le or in part, KIDDEL performs selective surgery on 
the file, removing parts of it entirely, or removing all the data 
entries from various parts of the file; this allows the file to begin 
a new life, reusing parts or all of its old skeletal structure. If, 
however, the MIDAS file has outlived its usefulness, KIDDEL will 
destroy it entirely, freeing up the disk space it formerly occupied. 

This digression was intended to give you some idea of how the utilities 
vgork together as a package, and to make you more comfortable with the 
v^iole idea of MiDAS- which isn't such a friahtful beast after all. 



MIDAS File Access Subroutines 

The ranainder of MIDAS consists of data access and maintenance 
subroutines. These subroutines, listed and explained briefly below, 
have been integrated into and are used indirectly by the following 
languages: BASIC/VM, CCBOL, PL/I and RPGII. 



REV, 1-10 



IDR4558 INTRODUCTIOJ TO MIDAS 



Special MIDAS access statement in those languages lets you obtain 
information frcan a MIDAS file without having to know anything about 
these MIDAS subroutines. FCKTRAN and PMA users can call these 
Sliaroutines directly from programs written in these languages. These 
subroutines are: 

• AED1$ adds an entry to a MIDAS file. 

• DELET$ deletes a data file or index subfile entry. 

• FIND$ locates a data file entry. 

• LOCK$ finds and locks entry for exclusive access. 

• NEXT$ locates next sequential entry in file. 

• UPDAT$ updates/rewrites a file entry. 

The calling sequences for these subroutines are discussed in Section 6. 

LANGUAGE-DEPENDENT LIMITATIOIS 

Although any of Prime's languages may be used to access a MIDAS file, 

must be kept in mind v*ien using MIDAS, This is especially true if a 
file is to be accessed by programs written in more than one language. 
Below are the restrictions on tonplate creation as they pertain to each 
language interface. Other restrictions pertaining to file access and 
maintenance are addressed separately in each of the language interface 
sections . 

BASIC/VM 

MIDAS files built for access by BASIC/VM programs can have up to 18 
keys: one primary and 17 secondaries. Although keys are not required 
to be part of the data record, it is recommended that both primary and 
secondary keys be included in the data record for convenience. 
BASIC/VM does not support the direct access feature of MIDAS. See 
Section 8 for BASIC/VM information. 



CCBOL 

A keyed-index MIDAS file, called an INDEXED SEQUENTIAL file in COBOL, 
can have up to six keys: one primary and five secondaries. If 
fixed-length records are desired, the data subfile record length 
indicated by the user during template creation ^io4;Q.d include the 
lengths of all primary and secondary key fields. This is because all 
keys must be included in the data record. Furthermore, the primary key 
must be the first field in the data subfile record. COBOL supports the 
direct access feature of MIDAS, enabling COBOL users to use direct 
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direct access feature of MIEftS, enabling COBOL users to use direct 
access MIDAS files, called RELATIVE files in COBOL, using the standard 
COBOL RELATIVE file I/O statanents. See Section 7 for information on 
INDEXED SEQUEOTIAL files, and Section 11 for details on RELATIVE files. 



FOyTRAN and PMA 

Because FCBTRAN is the principal MIDAS interface, and is in fact the 
basis of all the other language interfaces, FORTRAN and PMA users can 
take advantage of the full range of MIDAS features. Up to 17 secondary 
keys (and index subfiles) can be created per file. Keys do not have to 
be part of the data record, but it is easier to keep tabs on file 
integrity if they are. This simply means defining each key as an 
actual field in the record, as in the examples seen earlier in this 
section. See also Section 6. 



RPGII 

The RPG interface to MIDAS does not support the use of secondary keys 
or secondary data; only the primary key is recognized. Thus, records 
can be retrieved and reported on by primary key only. The size of the 
primary key is limited to 32 characters. Records in a MIDAS file can 
be updated or added through RPG, but cannot be deleted. RPGII supports 
access to both keyed-index and direct access MIDAS files. See also 
Section 10. 



PL/ 1 

The PI/I Subset G MIDAS interface supports only ASCII primary keys, 
with a maximum length of 32 characters. PL/I does not support these 
MIDAS features: secondary keys, secondary data or direct access. It 
is not necessary to use CREATK to set up a MIIS^ file template, as PL/ 1 
has its own tools for doing so. However, files created with CREATK can 
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INITIALIZING A MIDAS FILE 
(CREATK) 



INTRODUCTION 

MIDAS file creation involves tvuD essential steps: 

1. Initializing — definirig a template for the file to allocate 
space for all index and data subfiles. 

2. Building/converting a data file — adding data to the file (see 
Section 3 (KBUILD) , and also Sections 5-10) . 

This section deals with MIDAS file initialization, describing how to 
use CREATK in setting up a simple MIDAS file. Other CREATK functions 
are treated primarily in Sections 12 and 15. 



Language Interface Dependencies 

If you're getting acquainted with MIDAS for the first time, the 
importance of the language interfaces, to v^ich Section 1 made 
reference, may not be immediately apparent. The MIDAS utilities 
provide all the essential tools for building, maintaining and 
destroying a MIDAS data base, but they don't provide any tools for 
information extraction. That's v*iy the language interfaces are 
essential. They enable you to access (read), update, delete and add 
new information to MIDAS files. Without them, a MIDAS file vrould be a 
mass of inaccessible information. 

all the features of MIDAS, and others, only a few. Therefore, it's 
important to know v^at language interface you'll be using to access a 
file before you create that file; that vray you'll be able to tailor 
the file to the requirements of that particular language interface. 
These requirements and guidelines are all summarized in T^ble 2-1. 



SETTING UP A TEMPLATE 

CREATK is an interactive program that sets up a template based on 
user-supplied file specifications, often called "parameters," v*iich 
include : 

• MIDAS file type (keyed-index or direct access) 

• Primary key type and size 
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Table 2-1. Suranary of Interface R 


Language 
Interface 


Primary 
Ksy 


Secondary 
Keys 


BASIC/VM 


not required 
to be in data 
record, but 
is recommended 
for ease of use* 


up to 17 
(numbers 1-17) 




must reside in 


up to 5 


CCBOL 


data record and 
must be first 


(nunbers 1-5) 
must be defined 




field in record 


in order 



User Data Size 
(record-length) 



enter (CR) or 
for variable-length 
records; or enter 
record size in words 
for fixed-length 
records 

must include lengths 
of all key fields (in 
addition to non-key 
fields) if fixed- 
length records are 
desired; variable- 
length records are 
supported, but keys 
must reside in 
record . 



FOR-nm/ 
PMA 



not required 
to reside in 
data record 
(but reccxnmended) * 



PI/ 1 

(see Note) 



up to 17 
(nunbers 1-17) 



must be an ASCII 
key; default size 
is 32 chars. — 
does not have to be 

pQL I. UJ. Uai.CI JLCV.ULU 

but is reccanmended 
for ease of use* 



no secondary 
keys supported 



enter size in words 

for fixed-length 
records; enter (CR) 
or for variable- 
length records 

Variable-length 

records only, if 

creating file from 

PI/I program; fixed- 
ly— _4-u 3_ 

xcif^uii LCv;uLua 

supported if file was 
created with CREATK 



must reside in data 
RPGII record; does not 

have to be first 
field in record 



no secondary 
keys allowed 



fixed-length records 
only; size must 
include primary 
key 



Note 

PI/I prograitmers do not have to use CREATK when initializing a 
MIDftS file template. Pt/I can create one for you: see Section 
9 for details. 



Files with keys resident in the data record can 
with KBUILD. See Section 3 for details. 



be easily rebuilt 
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On page 2-3, the first sentaice should read: 

Secondary key types and sizes — these are optional and should be used 
when you want more than one search key for the file. Secondary search 
keys do not have to be part of the data record except in CDBCL. 
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• Secondary key types and sizes — these are optional and should 
be used v*ien you want more than one field per record to use a 
search key; the maximum nimber of secondary search keys 
allowable depends on the language interface v*iich will be used 
to access the file. (See Tables 2-1 and 2-3 for more 
information on keys and key types) . 

CREATK's Dialogs; Minimum Options vs. Full Options 
CREATK has two dialogs: 

• The "minimum options" dialog, which lets MIDAS supply default 
values for most of the structural parameters needed to build the 
template 

• Ihe "full options" dialog v*iich lets the user provide these 
parameter values 

With either CREATK dialog, the user can set up a keyed-index or direct 
access MIDAS file, depending on the access method desired. 

The real difference between the two dialogs is that the "full" (also 
called "extended") options path requires the user to supply more 
information. Under minimum options, a user can set up either a 
keyed-index or direct access file by answering a few simple questions 
about the file and its keys. The full options dialog, viiich asks the 
user for file size details like segment length and index block size, is 
discussed in Section 15. 

Generally, the minimum options path provides all the options most users 
need. Full or extended options features are required only v*ien the 
user wishes to increase or decrease the index block size. 



Minimum Options; Keyed-Index Dialog 

The remainder of this section explains the use of CREATK's minimum 
options path to create a keyed-index MIDAS file. If you want 
information on creating a direct access file, see Section 11. The 
extended options path is covered in Section 14. The complete dialog 
for creating a keyed-index file appears just below this discussion. 

All input to OREATK can be in lowercase or uppercase and must conform 
to the guidelines explained in Table 2-2. In cases of improper input, 
CREATK usually displays an explanatory message of some sort, telling 
you v^at it's looking for. This is repeated until a proper response is 
given. 
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l&ble 2-2. Minimum Options (Keyed-Index) Dialog 

Prcxnpt Response 

MINIMIW OPTIONS? YES (for simplest options path) 

FILE NAME? Ehter pathname of file to be 

created . 



JEW FILE? 

DIRECT ACCESS? 

DATA SUBFILE QUESTIOIS 
miMARY KEY TYPE: 

HIIMARY KEY SIZE=: 



EATA SIZE=: 



Ehter YES to 
template . 



create 



new 



Ehter NO to create keyed index 
file. 



Define primary key type; enter 
one of the key codes listed in 
table 2-3, below. 

Size can be specified with B nn, 
v^ere nn is number of bytes for 
an ASCII key or the nunber of 
bits for a bit string key; size 
can also be given in nunber of 
wsrds, W nn, for ASCII or bit 
string keys. See T&ble 2-3. 

Par fixed-length records, 

indicate maximum length of data 
record in the data subfile; 
size is expressed in viords . The 
length of all keys must be 
included in the data size for 
MIDAS files to be used in COBOL 
appx ica uions « 






for variable-length records. 



SEC(»IDARY INDEX 
INDEX NO? : 



Ehter nunber from 1-17 (FTO and 
BASIC/VM) or 1-5 (COBOL) , 

indicating which secondary index 
is being defined. In COBOL, 
secondary keys must be defined 
in order, that is, secondary key 
1 must be defined before 
secondary key 2, and so forth. 
Ehter or (CR) to terminate 
secondary index definition 
sequence . 
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DUPLICATE KEYS PERMITTED? 



KEY TYPE: 



Answer YES or NO, YES allows 
the same key value to appear in 
inore than one record. Duplicate 
values are legal for secondary 
keys only. 



Ehter one of 
l&ble 2-3. 



codes listed in 



KEY SIZE=: 



SECCNDARY DATA SIZE>=: 



Ehter size of key in vords, 
bytes or bits. See l^ble 2-3. 

Ehter number words of secondary 
data to be stored with this 
secondary key; for FCRTRAN and 
PMA only. Otherwise, enter or 
(CR). 
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Table 2-3. MIDAS File Key Types 



KEY CODE 



B 



D 



KEY TYPE 



ASCII 



Bit string 



Double Precision 
Floating Point 

Short Integer 
(INT* 2) 

Long Integer 
(INT* 4) 

Single Precision 
Floating Point 



Length deification 

Wbrds or Bytes : W nn or B nn 
Max. 32 words (64 bytes) 

Bits or Wbrds: B nn or W nn 
Max. of 16 words (32 bytes) 

Hardware-defined : 
4 words 

Hardware-defined : 

1 word 

Bterdware-def ined : 

2 words 

Hardware-defined : 
2 words 
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When CREATK asks a "YES/NO" -type question, it will accept any one 
of these possible responses: 

YES 

NO 

AYE 

NAY 

OK 

These responses can be abbreviated to one letter and can be typed 
in uppercase or lowercase. 

The CREATK dialog terminates v*ien the user hits (CR) in response to 
the INDEX NO? prompt. 

Key Types ; The data types for MIDAS keys are listed in l&ble 2-3. The 
maximum number of wrds per key is limited to 16 words for bit strings 
and 32 wrds for ASCII strings. The other data types are autcxnatically 
sized according to their internal specifications, as shovm in the 
table. 



A Sample File 

To help illustrate the basic features of CREATK, Figure 2-1 shows the 
layout of a saiiple MIDAS file vhich is used throughout the book to 
illustrate various MID^S concepts. This sample file is called 
CUSTOMER, and will contain information about certain vendors, including 
names, locations and regions. It could also contain order information, 
a sales rep name, etc. For simplicity, the file record has been 
limited to three major fields: customer code, a unique field which 
identifies each customer, the customer name field and the region code. 
The record can be expanded to accommodate more data, like the 
custcxner's address. 

The CUSTOMER file is a minimum options keyed-index file created with 
one primary key and tWD secondary keys. The primary key is an ASCII 
key, five characters in length; it describes the customer code, v^ich 
is a unique field in each file record. The first secondary key is an 
ASCII key of 25 characters referencing the customer name field of each 
file record. The second secondary key, a four character ASCII string, 
describes the region-code field. It will be canprised of a two-letter 
code describing one of six geograpiiic regions: 

MW mid-west 

NE north east 

NW north west 

SE south east 

SW south west 

WR western region (California, Nevada, etc.) 

and a two letter state code, taken from the standard two letter 
abbreviations for state names. 
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FIELD 1 


FIELD 2 


FIELDS 


FIELD 4 






CUSTOMER 
CODE 

(5 CHARACTERS) 


CUSTOMER 
NAME 

(25 CHARACTERS) 


LOCATION 
CODE 

(TWO LETTER 
REGION CODE; 
TWO LETTER 
STATE CODE) 


ADDRESS 

(35 CHARACTERS) 


























SECONDARY KEY 01 






NOT A KEYED FIELD 








ASCII KEY 

25 CHARACTERS 

NO DUPLICATES 










PRIMARY KEY 








SECONDARY KEY 02 






ASCII KEY 

5 CHARACTERS 

NO DUPLICATES 




ASCII KEY 

4 CHARACTERS 

DUPLICATES 

ALLOWED 





RECORD-LENGTH: 35 WORDS; 70 CHARS 



Figure 2-1. Layout of CUSTOMER File 
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Sample CREATK Dialog 

lb show you how the OvETCMER file template could be set up with CREATK, 
a canoutput file (PRIMOS caimand output file) , containing CREATK dialog 
pranpts and responses is listed below. The responses entered at the 
terminal by the user have been underlined to distinguish them frcxn 
CREATK' s prompts. This is only a text convention and is used only for 
clarity. Iton't attonpt to underline your input to CREATK (or to 
anything, else, for that matter). Nate that your responses can be 
entered in uppercase or lowercase letters. 

Because we want to access the file through all the language interfaces, 
we chose fixed-length records so there would be no anbiguities. Thus, 
the USER DATA SIZE is supplied as 35 words, giving the data file 
fixed-length records of 35 words (70 characters) each. 

Important Cbservations ; Ihe secondary data feature is not used, 
therefore a carriage return was supplied for this prcmpt. The use of 
secondary data is not reccmmended , and in fact is highly discouraged; 
see Appendix C. The convention for representing a carriage return in 
this docunent is (CR) . Understand that each line input to all MIDAS 
utilities must be terminated by a carriage return, the symbol appears 
only vAiere it's necessary to point out that a "null" response was 
entered to a particular pranpt. User input is underlined in all 
examples in this book to distinguish it frcan system output. 



OK, creatk 
[CREATK rev 17.6] 

MINIMUM OPTIONS? i«s 

FILE NAME? custcaners 
NEW FILE? yes 
DIRECT ACCESS? no 

DATA SUBFILE QUESTIONS 

PRIMARY KEY TYPE: a 
PRJMPRY KEY SIZE = : b 5 
DATA SIZE = : 35 

SECONDARY INDEX 

INDEX NO.? 1 

DUPLICATE KEYS PERMITTED? no 

KEY TYPE: a 

KEY SIZE = : b 25 

SECONDARY DATA SIZE = : (CR) 

INDEX NO.? 2 
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DUPLICATE KEYS PERMITTED? i^ 

KEY TYPE: a 

KEY SIZE = : b 4 

SECONDARY DATA SIZE = : (CR) 

INDEX NO.? (CR) 

SETTING FILE LOCK TO N READERS AND N WRITERS 

OK, 



OTHER THINGS TO KNOW ABOUT CREATK 

CREATK is a ccanplex utility, capable of performing many different 
tasks. So far this section has only given v^u a sampling of its 
repertoire. The next few pages describe some important things about 
CREATK that will help you use MIDAS and that will increase your 
understanding of how CREATK works and v*iat it does. 

File Read/Write locks 

By default, CREATK sets the file read/write lock on each MIDAS file it 
creates to n readers and n writers. Thia ia equivaleiiL Lu Uie PRIMOO 
nWLOCK aefcteing o f >. With a lock setting of 3, it is possible for one 
or more users to have the file open for reading, v*iile one or more 
users have it open for writing or updating. These default read/write 
lock settings are part of MIDAS' s concurrent process handling method, 
described in Section 13. 

CREATK displays the message: 

SETTING FILE LOCKS TO N READERS AND N WRITERS 

at the end of every session in which a new MIDAS file is created. 
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-S^^Sng tTset the file read-vrite lock to n readers and n writers. 
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Note 

If you use FUTIL to TELECOPY a MIDAS file frcan one location to 
another, the read/write lock settings of the file are reset to 
the systan default. Remonber to reset the locks on these files 
to 3 before attempting to access than from MIDAS. "Ihe lock on 
a particular file can be set with the SR subcarmand. Simply 
type: 

SR filename 3 

v*iere filename is the filename of the copied file. 

More CREATK Functions 

CREATK has many other options viiich allow you to obtain information 
about an existing MIDAS file, its key types and sizes, its index 
subfile structure, segment length, block size, etc. It is possible to 
add or modify new index subfiles. You can change the length of the 
data file record (expand it preferably) and get estimates on how much 
room is needed for a projfected nunber of entries, given a certain file 
layout, lb obtain a list of all these "old file" options, type H (for 
HELP) in response to the FUNCTiai? prompt. These options can only be 
used on existing files, i.e., viien you ansver "no" to the "NEW FILE?" 
prompt : 

OK, creatk 
[CREATK rev 17.6] 

MINIMUM OPTIONS? yes 

FILE NM1E? customers 
NEW FILE? no 

FUNCTICN? 



See Section 12, MIDAS FILE MAINTENANCE, for details on all the "old 
file" options of CREATK, which are surmarized below for your 
convenience . 
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Sunmary of CREATK Options 



Once you've indicated to CREATK that a file is an old or existing file 
(by entering "no" to the NEW FILE? prompt) , CREATK asks vhich FUNCTION 
you vant. The entire list of functions can be displayed by typing 
"help" : 



FUNCTICK? help 

A[DD] = AH) AN INDEX 

D[ATA] = CHANGE DATA RECORD SIZE 

E[XTEWD] = CHANGE SEGMENT SEQUENT DIRBCTCBY LENGTH 

F[ILE] = OPEN A NEW FILE 

H[ELP] = PRINT THIS SUMMARY 

M[ODIFY] = MODIFY AN EXISTING SUBFILE 

P[RINT] = PRINT DESCRIPTOR INFOFWATIC»J 

Q[UIT] = EXIT CREATK 

(C/R) = IMPLIED QUIT 

S[IZE] = DETERMINE THE SIZE OF A FILE 

U[SAGE] = DISPLAY CURRENT INMIX USAGE 

V[ERSION] = MIDAS DEFAULTS FOR TOIS FILE 



The brief descriptions provided by CREATK are expanded a bit in the 
following paragrafiis. For details on these functions and how to use 
them, see Section 12. 

ADD ; Allows you to add a secondary index subfile (and a key) to an 
existing MIDAS template. It does not let you add more than 17 
secondary index subfiles and won't allow you to specify index subfile 
17 as double-length (if you've enabled this feature: see Section 15). 

DATA ; Changes the data record length and the nuitoer of records 
allocated for that file if it is a direct access file; it does not 
display the current record length, so it must be known (use the PRINT 
option to get it : see below) . 

EXTEND : Lets you change the nutiber of segments per segment directory 
and wards per segment subfile. See Section 15 for more details. This 
effectively permits you to make bigger index and data subfiles by 
extending the segment subfile and segment directory lengths. 

FILE : Essentially re-starts CREATK; lets you create a new file 
template without returning to HRIMOS and re-entering CREATK, or WDrk on 
another old file. Returns you to PRIMOS after file definition is 
complete . 

HELP; Displays the list of functions as shovm above. 
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MODIFY ; Allows you to change support of duplicates; changes secondary 
data size; changes single to double-length index, if double-length 
indexes are supported. Also allows you to change the index block 
length, if using the extended options version of CREATK. See Section 
15. 

PRINT ; Describes each index subfile and the data subfile in terms of 
segments allocated, index capacity, key type, key size and nutnber of 
index levels for that subfile; for each level, it describes the entry 
size, block size, control wards, maximun number of entries per block 
and the nunber of blocks in that level. Data subfile information 
displayed, as of last MPACK, includes the file access type (keyed or 
direct) , the nunber of indexes, the entry size and the key size. See 
also Section 12. 

QUIT ; Exits the CREATK dialog and returns to PRIMOS. A carriage 
return does the same thing. 

SIZE ; Estimates the number of segments and disk records required for a 
hypothetical nunber of entries; estimates can be made for each index 
subfile, for the data subfile and the total file. See also Section 12. 

USAGE ; Provides information on the total nunber of entries in the 
file, the nunber of entries indexed, and the nunber of entries deleted, 
and the nunber of entries inserted since last MPACK; also displays the 
version of MID?^ Viiiich last modified the file. See also Section 12. 

VERSION ; Displays the rev. stamp of the version of MIDAS under which 
this particular file was created; also displays the default parameters 
for the file (DAM file length, segment directory length, segments 
index, etc.) . See also Section 12. 
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Ihere are several new messages output by KBUILD during the process of 
building a file. Most of than should not concern the user as they are 
sirrply informative and do not indicate difficulties. The diagnostic 
messages make more sense if you understand how KBUILD ^jes about 
building a MIDRS file. Briefly, KBUILD builds a MmAS file in one or 
more stages, called "passes." On each pass, one or more index siisfiles 
are built or are deferred for building during a subsequent pass. The 
KBUILD message: 

FIRST BUILD/t>EFER PASS (XIMPLETE 

siirply indicates that KBUILD has f ini^ed building the data subfile, 
(if the primary index needs to be built) and has built one or more 
indexes while possibly cfeferring the building of others. KBUILD defers 
the building of an index only if the irdex to be built is anpty and the 
user-provided input is unsorted. During the first pass KBUILD puts the 
unsorted input entries for each such index into a temporary "defer" 
file. After the first pass is oanplete, KBUILD sorts the individual 
defer files and builds the 'index subfiles from the now sorted data. 

Each time an index is sorted, KBUILD prints out a message indicating 
which index it is going to sort. After the sort is complete, the 
message: 

SORT ODMPLETE 

is printed. Similarly, KBUILD announces the building of each index. 
For example: 

BUffiDING INDEX 

After this index is built, the message: 

INDEX BUILT 

is displayed. When KBUILD has finished building the data subfile and 
all the index subfiles that needed to be built, it displays the 
message: 

KBUILD COMPLETE. 

and control returns to PRIM3S (unless you are running KBUILD out of a 
command file) . 
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SECTION 3 



BUILDING A MIDAS FILE 
(KBUILD) 



INTRODUCTIOVJ 

Throughout this book, the terms "building," "data entry" and 
"populating" all refer to the process of adding data to a MIDAS file. 
Chce you've set up a MIDAS file template there are several ways to add 
data to, or populate it. The alternatives are summarized below, along 
with references to other sections in this book vAiere you can find more 
information on populating MIDAS files. 

There are at least three ways to build a file (four, if you're 
progranming in BASIC/VM) . Che of these ways, the KBUILD utility, is 
documented in this section. The other methods: 

• implication Programs 

• Interactive Ehtry 

• Offline RDUtines 

are covered as indicated in T^ble 3-1. A quick comparison of these 
methods is also included to help you decide which method is best suited 
to your needs. 



When to Use KBUILD 

KBUILD is a quick and easy-to-use method of building a MIDAS file. 
With it, you can build both data and index subfiles from sequential 
disk files. KBUILD can also be used to add entries to a secondary 
index subfile, using entries in a sequential disk file or entries 
already present in the MIDAS data subfile associated with this index. 

With KBUILD yDU can build keyed-index MIDAS files containing either 
fixed- or variable-length records, and you can build direct access 
MIDAS files (vAiich always have fixed-length records) . Special direct 
access information is summarized at the end of this section under 
KBUILD AND DIRECT ACCESS. 
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Any of these file types can be processed by KBUILD: 

• ASCII text files (compressed) 

• PFWF$$-written binary files 

• FCRTRAN-written binary files 

• CCBOL-written "text" files with primary key as first 
field (uncompressed) 

• RPG-written files (uncompressed) 

These file types are further described in Table 3-2. 

When to Itee a Program 

Application programs to build MIDAS files require more vork of the user 
than does KBUILD. They should be used only v^en one or more of the 
following is true: 

• You don't have a pre-existing sequential disk file containing 
data in an easily convertible form. 

• It would require more work to prepare an existing data file for 
KBUILD than it would to simply use ADD1$ (FORTRAN call 
interface) , one of the "add" statements in the other language 
interfaces, or other offline routines. 

• A particular application program has already been written to 
handle updates, deletions, etc., and it would not require much 
effort to convert or modify it to perform record addition. 

• A series of finds, updates and adds must be done on a regular 
basis and it would be easier to take care of everything with a 
single applications program. 

• Other users may need access to the file even v*iile another 
program is adding entries to it. The only way to do this safely 
is to use the online routines like AIX)1$, either directly 
(through FCRTRRAN or PMA) or indirectly through COBOL, BASIC/VM, 
and so forth. KBUILD and the other offline routines (discussed 
in Section 14) must have single-user access to a file vAiile 
building it. However, they cannot guarantee that this remains 
true during the entire build process, so if another user or 
process accesses the file v*iile one of these routines has it 
open, the file will be damaged. 

Data entry as implemented in the various language interfaces is covered 
•in Sections 6 through 10. 
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Table 3-1. File-Building Alternatives 



Alternative 



When to Use 



Where to 
find Info 



KBUILD 

(interactive 

utility) 



Application 
Program 



Interactive 
Entry 



PRIBLD, 

SECBLD, 

BILD$R 

(offline 

routines^ 



Mainly for CCBOL, RPG and FTO 
programmers v*io already have 
existing data in sequential disk 
file. KBUILD adds entries from 
these input files to the index 
subfiles and data subfile of the 
MIDAS file template. Data in 
the input files must include a 
primary key and all records in 
the file must be formatted 
identically. Files can be in 
text, binary, CCBOL or RPG-type 
format: details below. 

Use this method when existing 
disk files are not in the form 
required by KBUILD, or vAien 
only a small number of 
records are being added. 

For BASIC/VM only; v*ien you want 
to add a few entries without a 
lot of progranming hassle. 

Users can call offline routines 
PRIBLD, SECBLD, and BILD$R to 
build a MIDAS file from existing 
sequential disk files; useful 
for adding concatenated keys 
or secondary data. See Section 
14 for details. 



Section 3 
(this one) 



Sections 6-10 



Section 8 



Section 14 
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Table 3-2. File lypes Supported by KBUILD 



File Type Code 



BINARY 



Description 

A binary file created by PRWF$$, vAiich is 
usually called frcm a FCRTRAN program. There 
are no newline characters (.NL.) in such a 

file. 



COBOL An ASCII file created by O$AD08, a routine 
called by CCBOL as a result of a WRITE 
statanent. The primary key must be the first 
field in the record. Ihese are uncompressed 
files with fixed-length records and newline 
characters as delimiters. 

FTOBIN A binary file created by a FORTRAN WRITE 
statement via the routine O$BD07, v*iich is used 
in FORTRAN binary output. The first word of 
each record in this type of file indicates the 
record-length of that record. Cbntains no 
newline characters. 



RPG 



A file created by the O$AD08 routine; an ASCII 
uncompressed file with fixed-length records and 
newline character delimiters. Records must 
contain the primary key but it doesn't have to 
be the first field in the record. 



TEXT An ASCII file (written with O$AD07) that has 
been passed through the EDITOR and is thus 
compressed. The records may be variable-length 
and are terminated by a newline character. 
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USING KBUllD 

Ihe remainder of this section describes all the important features of 
KBUILD, familiarizes you with the basic KBUILD dialog and variations 
thereof, and shows you how to use KBUILD in some typical situations. 

KBUILD' s Functions 

KBUILD' s range of functions are summarized below: 

• Adding data to a new ("empty") MIDAS file template and building 
(adding entries to) the necessary index subfiles from sorted or 
unsorted input data. 

• Adding new data and index entries to a MIDAS file that already 
contains data entries. 

• Adding entries from an external data file to a newly created 
secondary index subfile vAiich has just been added to an existing 
(and previously-populated) MIDAS file. 

• Converting a field from existing MIDAS data subfile records to a 
secondary key field and adding these entries to a new or already 
existing secondary index subfile. 

Most frequently, KBUILD is used \*_en a large quantity of records need 
to be added to a MIDAS file. For each record, KBUILD takes care of 
adding the primary index entry, the data subfile entry and any 
secondary index entries that have been supplied. Especially in cases 
v^ere lots of entries are being added to a file, it is recommended that 
you keep a "backup" copy of the input file or files in case of damage 
to the MIDAS file, or in case of a system crash v*iile the file is being 
processed. Set up a conmand file that first invokes CREATK to set up 
the template, then invokes KBUILD to populate the file. 

The user must know the following to use KBUILD: 

• The record structure of the input files (this shouldn't be a 
problem since the user will most likely set up the input file to 
suit the situation at hand) 

• The record size definition of the MIDAS data subfile as supplied 
to CREATK 

Note 

KBUILD does not process secondary data (it zeroes it out) and 
cannot handle concatenated keys. Use reiBLD and SECBLD to 
build a file with these features: see Section 14. 
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File Types Supported by KBUILD 

KBUILD supports input files with fixed-length records only. However, 
MIDAS files with variable-length records can be built by KBUILD, using 
specially formatted input files, as explained further under 
Variable-Length Records , below. Each file type supported by KBUILD is 
identified by its own type-code, as shown in Table 3-2, above. It's 
important that you know the type of file you're using before entering 
the KBUILD dialog, because KBUILD cannot process the input file without 
this information. 



Input File Rules 

Input files always have fixed-length records, regardless of v*iether the 
output (MIDAS) file contains fixed- or variable-ler^gth records. Ihe 
format of the input file record varies, depending on vAiat you intend 
KBUILD to do with the file. Input files can contain: 

• Primary key values and data values — secondary key 
values optional 

• Secondary key values only: must include primary key 
value in each input record so the record to be referenced 
can be located 

"Data" means the information that is to be written to the data subfile. 
Records do not have to be in sorted order, although it is recoitmended 
that they be sorted by any or all keys for faster processing. Some 
users may have existing files that they effectively want to "convert" 
into MIDAS files by using KBUILD. These files may or may not contain 
extraneous information that the user doesn't want processed. In any 
event, it's important to note that KBUILD expects certain things of 
input files and their record structure. The data record structure 
should be roughly laid out as follows: 

• Each record of the input file must begin with the pertinent data 
to be transferred by KBUILD to the appropriate parts of the 
MIDAS (output) file. In other words, the data to be placed in 
the index subfiles and in the data subfile must appear in the 
front of the input record. 

• No extraneous data can appear before the fields you want KBUIID 
to process. This restriction makes sense because it is easier 
for KBUILD to truncate the part of the record it doesn't need 
than to extract bits and pieces from a jumbled-up record. 



REV. 



IDR4558 KBUILD 



• KBUILD requires the user to specify the starting character 
position of each key field in the input record; this is also 
(-aj.icu uiic i-iyuc vjj.j.ocl. ui i.ne r>.ey i.j.crxu. iuc j.iLai_ cnardt-'ter 
position in the record is character position 1, not 0. Key 
fields must begin on byte (half-wrd) boundaries; they are not 
required to precede the data portion of the input record, except 
for the primary key in COBOL. They may appear after the data if 
they are not going to be physically part of the data subfile 
entry. 

• KBUILD requires the user to tell it the input record length. 
"This length is the number of words in an input record, not 
including anything inserted by the file systan, like .NL. 
characters or leading word count (in FTNBIN files) . The user 
doesn't have to tell KBUILD the length of the output file 
record, since it figures that out by reading the MIDAS file 
configuration. 

Note 

Fbr COBOL type files only, the primary key MUST begin in record 
position 1 (byte offset 1) of each input file record. RPG 
files do not require that the primary key start in position 
one. 



Where Keys Should Fteside 

Should you not want the keys to reside in the data subfile records, put 
them AFTER the data you want included in the data subfile entries. 
KBUILD can then truncate them vhen it writes the entries to the data 
subfile. Oily the initial portion of the input record (without keys) 
will be written to the MIDAS data subfile, femember, in CCBOL the 
primary key must begin in record position 1 but secondary keys can 
appear anywtiere 



Record Cbmpatibility 

Each record of the input file should have exactly the same record 
layout; that is, if the primary key starts in character position 1 of 
the first record, it should begin in the same position in each of the 
subsequent records in the input file. The same goes for any secondary 
key fields. Furthermore, it is assumed that the portion of each input 
record to be written to the output file always begins with vvord 1 of 
the input file record. Vhen writing a record from the input file to 
the output (MIDAS) file, KBUILD always begins with word 1 (character 
position 1) of the input record. "The actual length of the entry 
written to the output file depends on vAiether the MIDAS file has 
fixed-length records or variable-length records. RDr more information 
on this topic, see Building a MIDAS File With Variable-Length Records , 
below. 
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Sample Record Layout 

The following paragraphs and illustrations should give you an idea of 
record layouts for applications that require keys to reside in the data 
subfile record (like C(BOL) , and for applications that exclude keys 
from the data record. 

In the record layout pictured in Figure 3-la, the primary key starts in 
character position (byte offset) 1. Secondary key 01 starts in 
position 8. KBUILD knows how long the key is supposed to be by looking 
at the MIDAS file. Secondary key 02 starts in character position 15. 
The non-key portion of the input record begins at position 21 and vould 
continue for as many words as the user specifies. This record layout 
represents the kind of inpjt file structure you'd need to include the 
key fields in the data subfile record. Each record in this input file 
would follow the same pattern. 

Keys Not Resident in Data ; If keys were not included in the data 
subfile record, the record layout might look something like that shown 
in Figure 3-lb. 

The data portion of the record is 20 characters long; the primary key 
begins in character position 21; secondary key 01 starts in position 
28, and secondary key 02 starts in position 35. After the key values 
are written to their respective index subfiles, the first 20 characters 
(10 words) of the input record are copied to the data subfile. 



V\friat's Next 

Most of the general things you need to know about KBUILD have just been 
covered; the next part of this section discusses the particulars of 
using KBUILD, like: 

• Ebw to build variable-length output records from fixed-length 
input records 

• How to process multiple input files 

• The requirements for using sorted input files 

• Populating a direct access file with KBUILD 
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RECORD CHARACTER POSITION 



12 3 4 5 6 7 




11111 
8 9 12 3 4 




111112 
5 6 7 8 9 C 




2 Positions 22-39 * 

1 -• ^ 


Primary Key 
(7 charaeters) 




Sacondary Kay 

01 
(7 charactsrs) 




Sacondary 

Kay 02 

(6 characters) 




Data 

120 characters) 

10 words 



Figure 3- la. Keys Resident in Data 



RECORD CHARACTER POSITIONS 



Positions 2-19 



Data 

(20 characters) 

10 words 



2 2 2 2 2 2 2 

12 3 4 5 6 7 



2 2 3 3 3 3 3 
8 9 12 3 4 



Primary Key 
(7 characters) 



Secondary Key 

01 
(7 characters) 



Figure 3-lb. Keys Not Resident in Data 



Figure 3-1. Sample Record Layouts 



3 3 3 3 3 4 
5 6 7 8 9 



Secondary 

Key 02 

(6 characters) 



3 - 
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Building a MIDAS File With Variable-Length Records 

KBUILD can be used to process input files with fixed-length records for 
addition to MIDAS files that have variable-length records. There is a 
catch, however. In each record of the input file the user must 
indicate the number of words in that record viiich KBUILD should 
actually add to the data subfile. For ease of reference, let's call 
this piece of information the output record length. This record length 
can be specified as a bit string (an integer in binary form) or as an 
ASCII string. KBUILD asks you what form it's in so it can be properly 
converted. This number must appear at the same word position in each 
input file record. KBUILD asks vAiether the number is a bit string (B) 
or an ASCII string (A) during the dialog sequence, after it determines 
that your output file has variable-length records. 

For example, word number 15 of each of these input file records is used 
to indicate the nunber of words that should be processed from the 
record : 

2194GSpectrograpAiics 117 Lyons Blvd, Jamaica Pin. 

1002PFlora Portraits 11 Ramos Ave, Belleville 

9411PStudio West 09 Arcade Ct, Pasadena 

9402AArtistry Unltd. 10 Moorland St, Utica 

0816SMorrow Paper Mills 12 Vista Point, Monadnock 

2334PSeacoast Strippers 12 Seaspray In, Monterey 

4056SMark-Burton 09 Granger Rd, Belmont 

In this example, the output record length is in ASCII form, as the 
input file was created with the PRIMOG Editor (ED). Since it's not 
likely that the user wants the data transfer length to be included in 
the actual data written to the data subfile, so make this word number 
the last item in the input file record. It could also be put in the 
front of the record, but it would then become part of the data subfile 
record by default (and you probably wouldn't want it that way) . 

Requirements for Variable-Length Records ; When you have a MIDAS file 
with variable-length records, KBUILD assumes you want to add 
variable-length records to it, although it's perfectly reasonable to 
add fixed-length records to such a file. However, KBUILD requires you 
to specify the input record length, because it must have fixed-length 
input records to process. Therefore, even though KBUILD can add 
records to a variable-length MIDAS file, it requires the input file to 
have fixed-length records. Chce KBUILD has determined that the MIDAS 
file indeed has variable-length records, KBUILD prints out the 
following message: 

THE OUTPUT FILE SELECTED CONTAINS VARIABLE LENGTH DATA RECORDS. 
IS THE OUTPUT RECORD LENGTH SPECIFIED IN EACH INPUT RECORD 
AN ASCII STRING OR A BINARY (INT*2) STRING? (ENTER A OR B) : 

Your answer depends upon the format of the input file. 
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If the number is in ASCII format, and you entered "A" to the above 
prompt, KBUILD then asks: 

ENTER STARTING CHARACTER POSITICN IN INPUT RECORD: 
ENTER ENDING CHARACTER POSITION IN INPUT RECORD: 

Simply enter the starting and ending character positions of the output 
record length indicator in each input file record. 

If the number is a binary string (INT*2 nunber) , you must supply the 
vord number at vdiich the output record length indicator appears in the 
input file record: 

ENTER STARTING WORD NUMBER IN INPUT RECORD: 

Supply the ward number in the input file record reserved for the output 
record length indicator. If the input file does not have a word number 
set aside for this purpose, KBUILD cannot process the file properly and 
will abort. You can specify fixed-length records if desired by simply 
making the output record length the same in each input record. 

Note 

The routines PRIBLD, SECBLD and BILD$R are still available for 
users v*o would rather build variable-length MIDAS files that 

access files. See Section 14 for information. 



Multiple Input Files 

KBUILD allows more than one input file to be processed during a single 
run. This allows you to add information from several data files, up to 
100 of them, to a single MIDAS file. 

Note 

It is not possible to have more than one output file open at a 
time during a single execution of KBUILD. 

If more than one input file exists, the filenames must all begin with 
the same letters and end in a two-digit number, beginning with any 
two-digit number you want. For example: 

CUST01 
CUST02 
CUST03 

Up to 100 input files can be processed at a time. The files must all 
exist in the sane directory and must have exactly the sane format and 
file type. It is also assumed that the key fields begin in the same 
record position in all of the input files. 
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Sorted Input Files 

Input files can be sorted (in ascending order only) by primary and/or 
secondary key. If sorted by primary key, the data records and key 
entries are all added in primary key order. That is, the order of the 
entries in the data subfile will correspond to the order of the 
respective key entries in the primary index subfile. If the file 
contains secondary index entries for a subfile that allows duplicates, 
these duplicate keys will be added to the index subfile in the order in 
v*iich they are read from the input file. 

Pre-sorted index entries can only be added to an index that contains no 
entries. This is true for both primary and secondary index subfiles. 
There may be times vAien an index is for all purposes "empty" because it 
contains entries that point to deleted data subfile records. KBUILD 
can recognize that such an index is logically empty only if the primary 
index for that file is truly empty; this is because a file with an 
empty primary index doesn't have any data subfile records to be 
referenced, so any secondary index entries that exist are useless. 
When KBUILD notices that you are trying to build a non-atipty secondary 
index from a sorted input file, it tells you so. MPACK must be run on 
this index to clean it out before you can add sorted input entries to 
it. Otherwise, if the primary index does contain entries, you must run 
KIEOEL to clean out the secondary index subfile you want to build 
before trying to add sorted entries to it. 

Sort Requirements ; The KBUILD dialog asks whether input files are 
sorted or unsorted; if the files are sorted, it asks if the primary 
key field has been sorted. KBUILD then asks if any secondary key 
fields have been used as sort keys. Ihere are some restrictions on 
when a file can be properly called a "sorted" file: 

• If the input file records have not been sorted by a primary or 
secondary key field, the file is unsorted . 

• If there are several input files, they must all be sorted on the 
same field and all the sorted key values in the first file must 
be less than the sorted key values of the second file (and so on 
for as many files as you've got) in order to call the files 
sorted. This holds true for each sorted key field in the file. 
If either of these requirements is not met, the files must be 
declared unsorted. 

• Furthermore, if an index in the MIDAS file to v*iich the entries 
are being added already contains entries, do not declare the 
input files sorted by that key even if they are. If you do, 
KBUILD will catch this error and tell you about it. KBUILD 
cannot process an input file for building a MIDAS index that 
already contains entries if that input file is called "sorted." 

Multiple Sort Keys ; When a file is specified as "sorted," KBUILD asks 
whether this file (or files) is sorted by primary key. Regardless of 
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the user's answer to this question, KBUILD then asks vAiich secondary 
key it has been sorted on. Ihis prompt is repeated to allow the user 
to specify multiple index numiDers. You should then indicate the 
numbers of any secondary key fields by vAiich the input file has been 
sorted. If the file has not been sorted by a secondary key field, hit 
(CR) in response to this prompt. Do likewise v\*ien you've finished 
telling KBUILD v*iich secondary keys were used in sorting the file. 

Regardless of vAiether the input files are sorted or not, the data 
subfile entries are always stored in the order they are read in. Index 
entries are ultimately stored in sorted order, v^ether the user sorts 
than or not (it just saves time to pre-sort them) . Duplicates are 
stored in the order read in, regardless of sorting. 



Ajding Secondary Index Qitries Chly 

Mast of this discussion on KBUILD has been based on the assumption that 
all primary and secondary key entries are being added along with data 
subfile entries. Hawever, KBUILD is quite handy for populating a 
secondary index subfile v*ien: 

• You decide to make one of the fields in a MIDAS data record a 
secondary key. (You need more keys.) 

«Vri!i i^T/ln'^- CMTM^I \7 c<ar»rtrv^aK\7 l<ov t/al iioc oiTnrsl i pri -FriK all ■HHo ri^t'A 

entries you added originally; thus, this index subfile is 
"sparse," meaning there is not a one-to-one correspondence 
between index entries and data subfile entries. 

Tb accomplish this, you have twD choices: 

• Get the secondary index entries (key values) from the MIDAS data 
subfile records (i.e., make one of the fields in the data record 
a secondary key) . 

• T^ke the secondary index entries from an external input file. 
In this case, the primary key must be present in the input 
record . 

Remember — secondary index subfiles must be added to the template with 
CREATK before KBUILD can add entries to them. In other words, KBUILD 
can build the index subfiles as long as they've been properly defined, 
but KBUILD itself cannot define a new index subfile. 



The KBUILD Dialog 

To invoke the KBUILD utility, simply type KBUILD. Responses can be 
entered in upper- or lowercase, as is the case for all MIDAS utilities 
at Rev 17.6. The general KBUILD dialog is shown below, with prompts 
numbered for convenience. 
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Prompt 
1. SECCMiARIES OILY? 



2. USE MIDAS DATA? 



3. ENTER MIDAS FILENAME: 



4. ENTER INPUT FILENAME: 



Response 

Ehter y[ES] or N[0] : 

YES ; builds/adds entries to one 
or more secondary index subfiles. 
Dialog resumes at step 2. 
(Subfiles may or may not contain 
entries.) 

NO : adds data entries to data 
subfile by primary key. Bitries 
are also added to primary index 
subfile and any secondary index 
subfiles as indicated. Dialog 
resumes at step 4. 

Biter Y[ES] or N[0] : 

YES : existing data entries will 
be used as a source of values for 
a secondary index subfile (s). Do 
this v*ien you've got existing 
records in the data subfile and 
you vyant to make fields frcrn these 
records into secondary keys. 
Dialog continues with step 3. 

NO : all subfile and data subfile 
entries are taken fron an input 
file (not a MIDAS file) that must 
contain primary key values too. 
Use this method viien the MIDAS 
file being built does not contain 
any data entries. Dialog 
continues with step 4. 

Ehter pathname of MIDAS file from 
v*iich KBUILD should extract the 
secondary key entries; asked only 
if you answered YES to prompt 2. 
Dialog skips to step 14. 

Ehter pathname of input file to be 
processed by KBUILD. If using 
multiple files, simply enter the 
name of the one with the lowest 
sequence number. 



5. ENTER INPUT RECORD 
LENGTH (WORDS) : 



Ehter SI ze 
in words. 



of input file record 
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6. INPUT FILE TYPE: 



ENTER NlllBER OF FILES: 



Ehter one of the KBUILD file 
codes; see Table 3-2. 

Ehter 1 for single files; 
multiple input files, enter 
total number of files. 



type 



for 
the 



8. ENTER OUTPUT FILENAME: 



Ehter pathname of MIDftS file to 
vAiich input file is being added. 



(If the MIEftS output file has variable-length records, the 
next prompt is displayed. If the MIDAS file has 
fixed-length records, the dialog skips to step 13. Ebr 
direct access files, see KBUILD and DIRECT ACCESS, below.) 

9. TOE OUTPUT FILE SELECTED CONTAINS VARIABLE LENGTH DATA RECORDS, 
IS THE OUTPUT RECC«D LENGTH SPECIFIED IN EACH INPUT RECORD 
AN ASCII STRING OR A BINARy(INT*2) STRING? (ENTER h OR B) i 

In general (and this is a general statement, not a 
rule), if the input file was created with the Editor, 
CCBOL, or RPG, and the output record length is in ASCII 
form, enter "A"; dialog continues with step 10. If 
the input file is BINARY or FTOBIN enter "B"; dialog 
continues with step 12. 



10. ENTER STARTING CHARACTER 
POSITICaJ IN INPUT RECCRD: 



11. ENTER ENDING CHARACTER 

POSITIC*! IN INPUT REC(»D: 



12. ENTER STARTING WORD NUMBER 
IN INPUT RECORD: 



13. ENTER STARTING CHARACTER 
POSITION, PRIMARY KEY: 



Eliter the character position 
where the output record length 
specification begins. (Asked only 
if "A" specified above.) 

Ehter character position that 
marks the end of the output record 
length specification. (Asked only 
if "A" was specified for prompt 
9.) Dialog resumes with step 13. 

Enter the vrord number in the 
input record that specifies the 
output record length: for Binary 
(INT*2) representations only. 
(Asked only if "B" was specified 
in response to prompt 9.) 

Ehter starting position of field 
in input record which contains 
primary key value. (Asked only if 
answer to initial KBUILD prompt 
was NO.) 
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14. SECONDARY KEY NUMBER: 



Ehter number of secondary index 
subfile for vJiich an entry is to 
be taken frcan the input file 
record. This and the next prompt 
are repeated until the user hits 
(CR). 



15. ENTER STARTING CHARACTER 
POSITIOJ: 



16. IS THE FILE SORTED? 



Ehter character position in input 
record v*iere this secondary key 
field begins. 

Ehter YES only if the index being 
built contains no entries and the 
input file or files are indeed 
sorted (and all in the same vey) ; 
otherwise, enter NO, and the 
dialog resunes at step 19. 



(next two prompts asked only if you answered YES to previous prcanpt) 



17. IS THE PRIMARY KEY SORTED: 



18. ENTER INDEX NUMBER OF 
SECONDARY SORT KEY: 



Ehter YES if input file was sorted 
by primary key field. File may be 
sorted additionally by a secondary 
key field. Ehter NO if file was 
not sorted by primary key field. 
Not asked if building secondary 
index entries only. 

If file was sorted on a field that 
corresponds to a secondary key, 
enter that key (index subfile) 
number. Prompt is repeated until 
you hit (CR) . 



19. ENTER LOG/ERROR FILE NAME: 



Ehter name of file to be opened 
for recording errors and KBUILD 
statistics: see below. The 
filename should not be the name of 
an existing file. If it is, the 
existing file will be overwritten. 
Hit (CR) if you don't want the 
statistics recorded; they are 
still displayed at the terminal 
however . 
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20. ENTER MILESTCNE COUNT: Ehter interval (number of records) 

at which statistics should be 
displayed (arx3 optionally recorded 
in a log/error file) during 
processing of the input file. If 
you enter 0, milestones are 
printed for first and last records 
of input file only. 



Logging Errors and Milestones 

KBUILD automatically reports all errors and milestone statistics at the 
user's terminal. It also displays the name of the input file it is 
currently processing and tells you vAiat part of the MIDAS file it is 
currently in. This data can be optionally recorded in a log/error file 
which the user indicates during the KBUILD dialog. If you don't want 
such a file to be created, simply supply a carriage return (CR) v*ien 
KBUILD asks you for the log/error filename. The statistics vd.ll be 
displayed at the terminal but they won't be saved in a file. 

Milestone Reporting ; A milestone report consists of: 

• Ihe number of the record for vAiich the milestone is being 
generated 

• Ihe current date and time 

• The CPU time elapsed since KBUILD began processing this 
file 

• The disk time used since KBUILD began processing 

• The total disk and CPU time elapsed since the start of 
KBUILD' s run 

• The increment (of total time) elapsed since the last 
milestone was generated 

If the input file is unsorted, KBUILD also tells you vAien it begins and 
ends a sort pass through each set of index entries. 

Efere is an example of a milestone report for a sample run of KBUILD, 
using an laisorted input file. The milestone count is 1: 
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BUILDING: DATA 
DEFERRING: 0, 1 

PROCESSING FROM: var .names 

COUNT DATE TIME CPU MIN DISK MIN TOTAL "IM DIFF 

09-20-80 23:31:33 0.000 0.000 0.000 0.000 

1 09-20-80 23:31:33 0.002 0.000 0.002 0.002 

2 09-20-80 23:31:34 0.019 0.000 0.019 0.016 

3 09-20-80 23:31:34 0.020 0.000 0.020 0.001 

4 09-20-80 23:31:36 0.034 0.000 0.034 0.014 

5 09-20-80 23:31:36 0.035 0.001 0.036 0.002 
FIRST BUILD/DEFER PASS COMPLETE. 

5 09-20-80 23:31:36 0.036 0.001 0.037 0.001 



S(mTIN3 INDEX 
COUNT DATE 

09-20-80 
S(»T COMPLETE 

5 09-20-80 

BUILDING INDEX 



COUNT 




1 
2 
3 
4 
5 



DATE 
09-20-80 
09-20-80 
09-20-80 
09-20-80 
09-20-80 
09-20-80 



INDEX BUILT 

5 09-20-80 



TIME 
23:31:36 

23:31:36 



TIME 
23:31:36 
23:31:36 
23:31:36 
23:31:36 
23:31:36 
23:31:36 

23:31:37 



CPU MIN DISK MIN TOTAL TM 
0.000 0.000 0.000 



0.004 



0.000 



0.004 



CPU MIN DISK MIN TOTAL TM 



0.000 
0.001 
0.001 
0.002 
0.002 
0.002 

0.003 



0.000 
0.000 
0.000 
0.000 
0.000 
0.000 

0.000 



0.000 
0.001 
0.001 
0.002 
0.002 
0.002 

0.003 



DIFF 
0.000 

0.004 



DIFF 
0.000 
0.001 
0.000 
0.000 
0.000 
0.000 

0.001 



SOWING INDEX 1 
COUNT DATE TIME 

09-20-80 23:31:37 
SORT COMPLETE 

5 09-20-80 23:31:37 



CPU MIN DISK MIN TOTAL TM 
0.000 0.000 



0.004 



0.000 



0.004 



DIFF 
0.000 

0.004 



BUILDING INDEX 



COUNT 



INDEX 



DATE 
09-20-80 
09-20-80 
09-20-80 
09-20-80 
09-20-80 
09-20-80 
BUILT 
09-20-80 



TIME 
23:31:37 
23:31:37 
23:31:37 
23:31:37 
23:31:37 
23:31:37 

23:31:37 



CPU MIN DISK MIN TOTAL TM 



0.000 
0.001 
0.002 
0.002 
0.003 
0.003 

0.004 



0.000 
0.001 
0.001 
0.001 
0.001 
0.001 

0.001 



0.000 
0.002 
0.002 
0.003 
0.003 
0.004 

0.004 



DIFF 
0.000 
0.002 
0.000 
0.000 
0.000 
0.000 

0.001 



KBUILD COMPLETE. 
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Ihe milestones were done for each record in the input file because 
there were so few of them. Ebr larger files, set the milestone count 
to a more appropriate value depending on how concerned you are with 
resource us^e. 

If, for example, the milestone incranent is 10 and there are 35 records 
in the file, KBUILD prints the words: 

FIRST BUILD/DEFER PASS CCMPLETE. 

or 

INDEX XX BUILT 

before the milestone for record 35 is displayed. xx_ is the number of 
the index which was just completed. Fbllowing this message, the number 
35 will be displayed, indicating that a total of 35 records were added 
to the MIDftS file. 

Milestone Reports for Multiple Files ; If there are multiple input 
files, the name of each successive input file is displayed above the 
record count coliann as each new input file is processed. 

Error Reporting ; KBUILD reports any error (both fatal arxS non-fatal) 
that it encounters during processing. Errors can be file handler 
errors or MIDAS errors. The type and nunber of the error encountered 
are printed, along with the record number that was being processed v*ien 
this error occurred. Fatal errors are recorded in the log/error file 
just before KBUILD aborts. 



KBUILD Examples 

Ihe exam.ples shown below illustrate these features of KBUILD; 

• Building a fixed-length record MIDAS file from unsorted input 

• Building a fixed-length MIDAS file from sorted input 

• Building a variable-length record MIDAS file from text input 

• Building a secondary index frcsn existing data subfile entries 



- 19 Cfctober 1980 



SECTIC»i 3 II»4558 



Using Uhsorted Input ; In this example, an unsorted input file is used 
to build entries for the CUSTOMER file vAiich has fixed-length records 
of 35 words. Input files are not required to have the same record 
length as that of the output (MIDAS) file. When added, if they are too 
long, they are truncated, and if they are too short, they are 
blank-padded to the correct length. The input file contains the 
following records; 

2194GSpectrograiAiics NWCR 

1002PFlora Portraits NENY 

9411PStudio Vfest WRCA 

9402AArtistry IWtd. WRCA 

0816SNbrrow Paper Mills NENH 

2334PSeacoast Strippers WRCA 

4056SMark-Burton NEMA 

The file was built using the dialog shovm below: 

OK, kbuild 
[KBUILD rev 17.6] 

SECONDARIES ONLY? iio 

ENTER INPUT FILENAME: names 

ENTER INPUT RECCED LENGTH (WCPDS) : 35 

INPUT FILE TYPE: t 

ENTER NUMBER OF INPUT FILES: 1 

ENTER OUTPUT FILENAME: custcaner 

ENTER STARTING CHARACTER P0SITIC»1, PRIMARY KEY: 1 

SECONDARY KEY NUMBER: 1 

ENTER STARTING CHARACTER POSITION: 6 

SECONDARY KEY NUMBER: 2 

ENTER STARTING CHARACTER POSITION: 31 

SECCMJARY KEY NUMBER: (CR) 

IS FILE SORTED? n 

ENTER LOG/ERROR FILE NAME: (CR) 

ENTER MILESTdJE COUNT: 1 
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BUILDING: DATA 












DEFERRING: 0, 1, 2 












PROCESSING FROM: names 










COUNT DATE 


TIME 


CPU MDI 


DISK MIN 


TOTAL TM 


DIFF 


09-23-80 


10:28:50 


0.000 


0.000 


0.000 


0.000 


1 09-23-80 


10:28:50 


0.002 


0.001 


0.003 


0.003 


2 09-23-80 


10:28:50 


0.002 


0.001 


0.003 


0.001 


3 09-23-80 


10:28:50 


0.003 


0.001 


0.004 


0.001 


4 09-23-80 


10:28:50 


0.003 


0.001 


0.005 


0.001 


5 09-23-80 


10:28:50 


0.004 


0.001 


0.005 


0.001 


FIRST BUILD/DEFER PASS COMPLETK. 








5 09-23-80 


10:28:51 


0.004 


0.001 


0.006 


0.001 


SORTING INDEX 












COUNT DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL TM 


DIFF 


09-23-80 


10:28:51 


0.000 


0.000 


0.000 


0.000 


SORT COMPLETE 












5 09-23-80 


10:28:51 


0.004 


0.000 


0.004 


0.004 


BUILDIN3 INDEX 












COUNT DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL TM 


DIFF 


09-23-80 


10:28:51 


0.000 


0.000 


0.000 


0.000 


1 09-23-80 


10:28:51 


0.001 


0.000 


0.001 


0.001 


2 09-23-80 


10:28:51 


0.001 


0.000 


0.001 


0.000 


3 09-23-80 


10:28:51 


0.002 


0.000 


0.002 


0.000 


4 09-23-80 


10:28:51 


0.002 


0.000 


0.002 


0.000 


5 09-23-80 


10:28:51 


0.002 


0.000 


0.002 


0.000 


INDEX BUILT 












5 09-23-80 


10:28:51 


0.003 


0.000 


0.003 


0.001 


SORTING INDEX 1 












COUNT DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL TM 


DIFF 


09-23-80 


10:28:52 


0.000 


0.000 


0.000 


0.000 


SORT COMPLETE 












5 09-23-80 


10:28:52 


0.004 


0.000 


0.004 


0.004 


BUILDING INDEX 1 












COUNT DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL TM 


DIFF 


09-23-80 


10:28:52 


0.000 


0.000 


0.000 


0.000 


1 09-23-80 


10:28:52 


0.002 


0.001 


0.002 


0.002 


2 09-23-80 


10:28:52 


0.002 


0.001 


0.003 


0.000 


3 09-23-80 


10:28:52 


0.002 


0.001 


0.003 


0.000 


4 09-23-80 


10:28:52 


0.003 


0.001 


0.004 


0.000 


5 09-23-80 


10:28:52 


0.003 


0.001 


0.004 


0.000 


INDEX 1 BUILT 












5 09-23-80 


10:28:52 


0.004 


0.001 


0.005 


0.001 


SORTING INDEX 2 












COUNT DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL 1W 


DIFF 


09-23-80 


10:28:52 


0.000 


0.000 


0.000 


0.000 


SORT COMPLETE 












5 09-23-80 


10:28:53 


0.004 


0.000 


0.004 


0.004 
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COUNT 




DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL TM 


DIFF 







09-23-80 


10:28:53 


0.000 


0.000 


0.000 


0.000 




1 


09-23-80 


10:28:53 


0.001 


0.001 


0.003 


0.003 




2 


09-23-80 


10:28:53 


0.002 


0.001 


0.003 


0.000 




3 


09-23-80 


10:28:53 


0.002 


0.001 


0.003 


0.000 




4 


09-23-80 


10:28:53 


0.003 


0.001 


0.004 


0.000 




5 


09-23-80 


10:28:53 


0.003 


0.001 


0.004 


0.000 


INDEX 


2 


BUILT 














5 


09-23-80 


10:28:53 


0.004 


0.001 


0.005 


0.001 



KBUILD COMPLETE. 

Using Sorted Input : If the CUSTOMER file is built from sorted input 
records, the build is faster because KBUILD doesn't have to sort the 
records itself. This is the sorted input file (sorted on primary key) : 

0816SMorrow Paper Mills NENH 

1002PFlora Portraits NENY 

2194GSpectrograE*iics NWCR 

9402AArtistry Lfriltd. WRCA 

9411PStudio Wfest WRCA 

The KBUILD-user dialog used to build this file is: 

OK, kbuild 
[KBUILD rev 17.6] 

SECONDARIES ONLY? no 

ENTER INPUT FILENAME: names. sort 

ENTER INPUT RECCM) LENGTH (WC«DS) : 17 

INPUT FILE TYPE: text 

ENTER NUMBER OF INPUT FILES: 1 

ENTER OUTPUT FILENAME: customer 

ENTER STARTING CHARACTER POSITION, PRIMARY KEY: 1 

SECONDARY KEY NUMBER: _1 

ENTER STARTING CHARACTER POSITIOJ: 6 

SECONDARY KEY NUMBER: 2 

ENTER STARTING CHARACTER POSITION: ^1 

SECONDARY KEY NUMBER: (CR) 

IS FILE SCM^TED? yes 

IS THE PRIMARY KEY SORTED? yes 

ENTER INDEX NI^IBER OF SECONDARY SORT KEY: (CR) 

ENTER LOG/ERROR FILE NAME: (CR) 

ENTER MILESTONE COUNT: 1 
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BUILDING: DATA, 
OEFERRmS: 1, 2 



PROCESSING FRCM: names. sort 

COUNT DATE TIME CPU MIN DISK MIN 

09-22-80 15:28:45 0.000 0.000 

1 09-22-80 15:28:45 0.002 0.003 

2 09-22-80 15:28:45 0.002 0.003 

3 09-22-80 15:28:45 0.003 0.003 

4 09-22-80 15:28:45 0.003 0.003 

5 09-22-80 15:28:45 0.004 0.003 
FIRST BUILD/DEFER PASS COMPLETE. 

5 09-22-80 15:28:46 0.004 0.003 



TOTAL IW 
0.000 
0.004 
0.005 
0.005 
0.006 
0.006 

0.007 



SCm-ING INDEX 1 
CCXJNT DATE 

09-22-80 
SCX^T COMPLETE 

5 09-22-80 

BUILDING INDEX 1 



COUNT 




1 
2 



DATE 
09-22-80 
09-22-80 
09-22-80 



3 09-22-80 

4 09-22-80 

5 09-22-80 
INDEX 1 BUILT 

5 09-22-80 

SORTING INDEX 2 
COUNT DATE 

09-22-80 
SORT COMPLETE 

5 09-22-80 

BUILDING INDEX 2 
COUNT 



inmx 



DATE 
09-22-80 
09-22-80 
09-22-80 
09-22-80 
09-22-80 
09-22-80 
BUILT 
09-22-80 



TIME 
15:28:46 

15:28:47 



TIME 
15:28:47 
15:28:47 
15:28:47 
15:28:47 
15:28:47 
15:28:47 

15:28:47 



TIME 
15:28:47 

15:28:48 



TIME 
15:28:48 
15:28:49 
15:28:49 
15:28:49 
15:28:49 
15:28:49 

15:28:49 



CPU MIN DISK MIN TOTAL TM 
0.000 0.000 0.000 



0.004 



0.005 



0.009 



CPU MIN DISK MIN TOTAL 1M 



0.000 
0.002 
0.002 
0.003 

0.003 
0.003 

0.004 



0.000 
0.002 
0.003 
0.003 
0.003 
0.003 

0.003 



0.000 
0.004 
0.005 
0.006 
0.006 
0.007 

0.007 



CPU MIN DISK MIN TOTAL TM 
0.000 0.000 0.000 



0.003 



0.000 



0.003 



CPU MIN DISK MIN TOTAL TM 



0.000 
0.002 
0.002 
0.002 
0.003 
0.003 

0.004 



0.000 
0.002 
0.002 
0.002 
0.002 
0.002 

0.002 



0.000 
0.003 
0.004 
0.004 
0.004 
0.005 

0.006 



KBUILD COMPLETE. 



DIFF 
0.000 
0.004 
0.001 
0.001 
0.001 
0.001 

0.001 



DIFF 
0.000 

0.009 



DIFF 
0.000 
0.004 
0.001 
0.000 
0.000 
0.000 

0.001 



DIFF 

0.000 

0.003 



DIFF 
0.000 
0.003 
0.001 
0.000 
0.000 
0.001 

0.001 
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Note that the primary index entries were not sorted during this run of 
KBUILD because we told it that they'd already been sorted. However, 
the secondary index entries were sorted by KBUILD as indicated by the 
explanatory messages. 

Building Variable-length Ftecords ; MIDAS files with variable-length 
records can loe built by KBUILD, but the user must supply KBUILD with 
the length of each data record to be written to the output file. This 
example shows the prompts needed to create a keyed index file with 
variable-length records, the input file with the output record length 
indicated in each record and the user/KBUILD dialog needed to build 
this MIDAS file. 

OK, creatk 
[CREATK rev 17.6] 

MINIMUM OPTI»IS? yes 

FILE NAME? varcust 
NEW FILE? yes 
DIRECT ACCESS? no 

DATA SUBFILE QUESTIONS 

PRIMARY KEY TYPE: a 
reiMARY KEY SIZE = : b 5 
CftTA SIZE = : (CR) 

SECONDARY INDEX 

INDEX NO.? jL 

DUPLICATE KEYS PERMITTED? ^es 

KEY TYPE: a 

KEY SIZE = : b 25 

SECONDARY DATA SIZE = : (CR) 

INDEX NO.? 2 

DUPLICATE KEYS PEIWITTED? ^^es 

KEY TYPE: a 

KEY SIZE = : b 4 

SECONDARY DATA SIZE = : (CR) 

INDEX NO.? (CR) 

SETTING FILE LOCK TO N READERS AND N WRITERS 



The input file used in building the MIDAS file is called VAR.NAMES. 
Although each output record is different in length, KBUILD needs to 
know the input data record length. In this case, it is 22 words. Each 
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record in the file contains a nun±)er that indicates the output record 
length for that particular record. This length tells KBUILD how many 
WDrds of the input record to write to the data subfile. Ihe output 
record length begins in character position 30 and ends in character 
position 31 of each record. Observe that the address information will 
not be written to the file as part of the data subfile record. At a 
later time however, another index could be created and the address 
field corresponding to each record in the data subfile could be added 
to the new index subfile. 

2194GSpectrographics 11 7 Lyons Blvd, Jamaica Pin. 

1002PFlora Portraits 11 Ramos Ave, Belleville 

9411PStudio Vfest 09 Arcade a, Pasadena 

9402AArtistry IKLtd. 10 Moorland St, Utica 

0816a%>rrow Paper Mills 12 Vista Point, Monadnock 

2334PSeacoast Strippers 12 Seaspray In, Monterey 

4056SMark-Burton 09 Granger Rd, Belmont 

Since the output record length is in ASCII form, we tell KBUILD v*iat 
character positions it begins and ends in, that is, 30 and 31. If the 
nunber were in binary (INTEX3ER*2) form, we'd indicate the word number 
that the entry nunber begins in. Ihe KBUILD dialog and user responses 
for the above example are as follows: 

OK, kbuild 

LfUJuj.jjj-' icV JLf.Oj 

SECCMftRIES OJLY? r» 

ENTER INPUT FILENAME: var .nanes 

ENTER INPUT RECORD LENGTH (WOyDS) : 22 

INPUT FILE TYPE: t 

ENTER NUMBER OF INPUT FILES: 1 

ENTER OUTPUT FILENAME: varcust 

THE OUTPUT FILE SELECTED CONTAINS VARIABLE LENGTH DATA RECORDS. 

IS THE OUTPUT RECCM) LaJGTH SPECIFIED IN EACH INPUT RECORD 

AN ASCII STRING OR A BINARY (INT*2) STRING? (ENTER A OR B) : a 

ENTER STARTING CHARACTER POSITION IN INPUT RECORD: 30 ~ 

ENTER ENDING CHARACTER POSITION IN INPUT RECORD: 31 

ENTER STARTING CHARACTER POSITION, PRIMARY KEY: 1 — 

SECONDARY KEY NUMBER: 1 ~ 

ENTER STARTING CHARACTER POSITION: 6 

SECCMDIARY KEY NUMBER: (CR) ~ 

IS FILE SORTED? no 

ENTER LOG/ERROR FILE NAME: (CR) 

ENTER MILESTONE COUNT: 1 



3-25 October 1980 



SEXn-IOJ 3 



im4558 



BUILDING: DATA 
DEFERRING: 0, 1 



PROCESSIN 


G FROM: var .names 










COUNT 


DATE TIME CPU MIN 


DISK MIN 


TOTAL TM 


DIFF 





09-30-80 23:55:13 


0.000 


0.000 


0.000 


0.000 


1 


09-30-80 23:55:13 


0.002 


0.000 


0.002 


0.002 


2 


09-30-80 23:55:13 


0.002 


0.000 


0.002 


0.001 


3 


09-30-80 23:55:14 


0.003 


0.000 


0.003 


0.001 


4 


09-30-80 23:55:14 


0.003 


0.000 


0.003 


0.001 


5 


09-30-80 23:55:14 


0.004 


0.000 


0.004 


0.001 


FIRST BUILD/DEFER PASS COMPLhTE. 










5 


09-30-80 23:55:15 


0.004 


0.000 


0.004 


0.001 



SCS^TING INEEX 
COUNT DATE TIME CPU MIN DISK MIN TOTAL TM DIFF 

09-30-80 23:55:15 0.000 0.000 0-000 0-000 

SORT COMPLETE 

5 09-30-80 23:55:16 0.004 0.000 0.004 0.004 

BUILDING INDEX 



COUNT 


DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL TM 


DIFF 





09-30-80 


23:55:16 


0.000 


0.000 


0.000 


0.000 


1 


09-30-80 


23:55:17 


0.001 


0.000 


0.001 


0.001 


2 


09-30-80 


23:55:17 


0.001 


0.000 


0.001 


0.000 


3 


09-30-80 


23:55:17 


0.002 


0.000 


0.002 


0.000 


4 


09-30-80 


23:55:17 


0.002 


0.000 


0.002 


0.000 


5 


09-30-80 


23:55:17 


0.002 


0.000 


0.002 


0.000 


INDEX BUILT 












5 


09-30-80 


23:55:18 


0.003 


0.000 


0.003 


0.001 


SORTING INDEX 1 












COUNT 


DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL m 


DIFF 





09-30-80 


23:55:18 


0.000 


0.000 


0.000 


0.000 


SORT COMPLbTE 












5 


09-30-80 


23:55:20 


0.004 


0.000 


e.mA 


0.004 


BUILDING 


IMEX 1 












COUNT 


DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL TM 


DIFF 





09-30-80 


23:55:20 


0.000 


0.000 


0.000 


0.000 


1 


09-30-80 


23:55:20 


0.002 


0.000 


0.002 


0.002 


2 


09-30-80 


23:55:21 


0.002 


0.000 


0.002 


0.000 


3 


09-30-80 


23:55:21 


0.003 


0.000 


0.003 


0.000 


4 


09-30-80 


23:55:21 


0.003 


0.000 


0.003 


0.000 


5 


09-30-80 


23:55:21 


0.003 


0.000 


0.003 


0.000 


INDEX 1 


BUILT 












5 


09-30-80 


23:55:21 


0.004 


0.000 


0.004 


0.001 



KBUILD COMPLETE. 
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Building a Secondary Index From MIEftS Data t Suppose we only built the 
primary and one secondary index during the KBUILD as shovm in the first 
exaniple. At a later time we decide to add another secondary index to 
the file so that we can use the region code information as a search 
key. Since the information is already present in the data subfile 
record (we wrote the entire input record to the data sifcfile) , we can 
tell KBUILD to take the secondary index entries from the data subfile 
record and add them to secondary index subfile 2. This example shows 
how. Keep in mind that v^'re working with a MIDAS file that already 
contains data entries. 

lb add a new secondary index to a file, use the ATO option of CREATK 
(see Section 12 for details) : 

OK, creatk 

MINIMUM OPTIOIS? y 

FILE NAME? custoner 
NEW FILE? n 

FUNCTION? add 

INDEX NO.? 2 

KJPLICATE KEYS PERMITTED? ^es 

KEY TYPE: a 

KEY SIZE = : b 4 

SECOCftRY DATA SIZE = : (CR) 



INDEX NO.? (CR) 

FUNCTION? q 

Entries were added to the new secondary irrfex by providing KBUIIJ) with 
the information as shown in this sample session: 

OK, kbuild 
[KBUILD rev 17.6] 

SECONDARIES OILY? yes 

USE MIDAS DATA ENTRIES? yes 

ENTER MIEftS FILENAME: customer 

SECCMDARY KEY NUMBER: 2 

ENTER STARTING CHARACTER POSITIOl: 31 

SECCMiARY KEY NUMBER: (CR) 

IS FILE SCRTED? n 

ENTER LOG/ERROR FILE NAME: (CR) 

ENTER MILESTONE COUNT: 1 
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DEFERRING 


: 2 












PROCESSING FRCM: customer 










COUNT 


DATE 


TIME 1 


CPU MIN 


DISK MIN 


TOTAL TO 


DIFF 





10-01-80 


11:36:15 


0.000 


0.000 


0.000 


0.000 


1 


10-01-80 


11:36:16 


0.001 


0.001 


0.002 


0.002 


2 


10-01-80 


11:36:16 


0.002 


0.001 


0.003 


0.001 


3 


10-01-80 


11:36:16 


0.002 


0.001 


0.003 


0.000 


4 


10-01-80 


11:36:16 


0.003 


0.001 


0.004 


0.001 


5 


10-01-80 


11:36:16 


0.003 


0.001 


0.004 


0.000 


FIRST BUILD/DEFER PASS CCMPLETE 


• 








5 


10-01-80 


11:36:16 


0.004 


0.001 


0.005 


0.001 



SORTING INDEX 2 
COUNT DATE TIME CPU MIN DISK MIN TOTAL TO DIFF 

10-01-80 11:36:16 0.000 0.000 0.000 0.000 

SORT COMPLETE 

5 10-01-80 11:36:17 0.003 0.000 0.003 0.003 



BUILDING 


INDEX 2 












COUNT 


DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL TO 


DIFF 





10-01-80 


11:36:17 


0.000 


0.000 


0.000 


0.000 


1 


10-01-80 


11:36:17 


0.002 


0.001 


0.003 


0.003 


2 


10-01-80 


11:36:17 


0.002 


0.001 


0.003 


0.000 


3 


10-01-80 


11:36:18 


0.002 


0.001 


0.004 


0.001 


4 


10-01-80 


11:36:18 


0.003 


0.001 


0.004 


0.000 


5 


10-01-80 


11:36:18 


0.003 


0.001 


0.004 


0.000 


INMX 2 BUILT 












5 


10-01-80 


11:36:18 


0.004 


0.001 


0.005 


0.001 



KBUILD CCMPLETE. 

The MIDAS file now contains five entries in each of the indexes and the 
data subfile. (You can use CREATK to verify this.) 
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KBUILD AND DIRECT ACCESS 

Ihs remainder of this sectiorx is meant only for users with direct 
access MIDAS files. Direct access MIDAS files are called REIATIVE 
files in COBOL, and DIRECT files in RPG. 



Building Direct Access Files 

Practically everything said above about building keyed-index MIDAS 
files applies to direct access MIDAS files. The only major differences 
are: 

• A record number must be supplied for each record — the data 
type must be a REAL*4 (floating-point) number in the form of a 
bit string, or it can be an ASCII string. 

• The record number must h>e placed at the same character position 
in each input record. 

• In CCBOL files, the record number must be the primary key. 

• In non-C(BOL files, a primary key can be supplied in addition to 
a record number (the record nunber doesn't have to be the 
primary key) . A direct access file can have up to 999,999 
entries. 



KBUILD Dialog Requirements 

When KBUILD determines that the MID?^ output file is a direct access 
file, it prints the following message: 

IS THE ENTRY NUMBER SPECIFIED IN EACH INPUT RECORD 

AN ASCII STRING OR A BINARY (REAL*4) STRING? (ENTER A CR B) : 

KBUILD then prompts for the beginning and ending character positions of 
the record number if it is an ASCII string. If the number is specified 
as a single-precision floatir^-point bit string, KBUILD asks for the 
wprd number (not character position) at which the number begins in the 
record. If the vord number is beyond the logical end of the record 
vAiich you specified earlier in the dialog, KBUILD will warn you about 
it. See Section 11 for information on direct access (RELATIVE) files 
in CCeOL. For more information on direct access files in RPG, see 
Section 10. 

Direct Access Example : A direct access file can be built with KBUILD, 
providing that you include record entry numbers for each record in the 
input file. Numbers can be written in ASCII or binary (floating point) 
form and should match the key type specification for the primary key if 
the primary key was defined as the record nurnber, v*iich is always the 
case in CCBOL and RPG. 

Ebr example, this CREATK session sets up a direct access file with a 
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primary key declared as a 48-bit bit string. (This means it can be 
treated as a REEATIVE file in CCBOL, because the primary key will be 
the record number.) 

OK, creatk 
[CREATK rev 17.6] 

MINIMUM OPTIOJS? ^es 

FILE NAME? dacust 
NEW FILE? yes 
DIRECT ACCESS? yes 

DATA SUBFILE QUESTICNS 

PRIMARY KEY TYPE: b 

PRIMARY KEY SIZE = : b 48 

EATA SIZE = : 22 

NIWBER OF ENTRIES TO ALLOCATE? 10 

SECONDARY INDEX 

INDEX NO.? (CR) 

SETTING FILE LOCK TO N READERS AND N WRITERS 

The input file used to build the direct access file created above is 
shown below. Because we didn't want the record number to be part of 
the data subfile record, we put it after the fields that we did vrant 
included in the data subfile record. Thus the direct access entry 
nunber appears in positions 37 - 42 of the input file record. The 
nimbers, like the entire input file, are written in ASCII format. 
CCBOL programers might want to do scmething similar vAien building a 
RELATIVE file with KBUILD. The file used as input to KBUILD contains 
these records: 



2194GSpectrograi*iics 
1002PFlora Portraits 
941lPStudio Wfest 
9402AArtistry Unltd. 
0816SMorrow Paper Mills 
2334PSeacoast Strippers 
40569terk-Burton 



NWOR 000001 

NENY 000002 

WRCA 000003 

WRCA 000004 

NENH 000005 

WRCA 000006 

NEMA 000007 
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This file was processed by KBUILD in the sample session shown here: 

OK, kbuild 
[KBUILD rev 17.6] 



SECC»rcftRIES aaLY? no 
ENTER INPUT FII£NAME: 



da .names 



21 



ENTER INPUT RECORD LENGTH (WCRDS) 

INPUT FILE TYPE: t 

ENTER NUMBER OF INPUT FILES: 1 

ENTER OUTPUT FILENAME: dacust 

THE OUTPUT FILE SELECTED IS A DIRECT ACCESS FILE. 

IS THE ENTRY NIMBER SPECIFIED IN EACH INPUT RECORD 

AN ASCII STRING OR A BINARY (REAL*4) STRING? (ENTER A CR B) : a 

ENTER STARTING CHARACTER POSITIC»J IN INPUT RECCM): 37 

ENTER ENDING CHARACTER POSITION IN INPUT RECCRD: 42 

ENTER STARTING CHARACTER POSITICN, H^IMARY KEY: 37 

SECCM)ARY KEY NUMBER: (CR) 

IS FILE SORTED? n 

ENTER LOG/ERROR FILE NAME: (CR) 

ENTER MILESTONE COUNT: 1 

BUILDING: DATA 
EEFERRIM3: 



PROCESSING FROM: 
COUNT DATE 

10-20-80 

1 10-20-80 

2 10-20-80 

3 10-20-80 

4 10-20-80 

5 10-20-80 

6 10-20-80 
FIRST BUILD/DEFER PASS COMPLETE. 

6 10-20-80 23:59:50 



da.nanes.new 
TIME 
23:59:50 
23:59:50 
23:59:50 
23:59:50 
23:59:50 
23:59:50 
23:59:50 



CPU MIN 
0.000 
0.002 
0.002 
0.003 
0.003 
0.004 
0.005 

0.005 



DISK MIN 
0.000 
0.000 
0.000 
0.000 
0.000 
0.000 
0.000 

0.000 



TOTAL TO 
0.000 
0.002 
0.002 
0.003 
0.003 
0.004 
0.005 

0.005 



SORTING IHCEX 
COUNT DATE TIME CPU MIN DISK MIN TOTAL TO 

10-20-80 23:59:50 0.000 0.000 0.000 

SCHT COMPLETE 

6 10-20-80 23:59:51 0.004 0.000 0.004 



DIFF 
0.000 
0.002 
0.001 
0.001 
0.001 
0.001 
0.001 

0.001 



DIFF 
0.000 

0.004 
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BUILDING 


INDEX 












COUNT 


DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL TM 


DIFF 





10-20-80 


23:59:51 


0.000 


0.000 


0.000 


0.000 


1 


10-20-80 


23:59:51 


0.001 


0.000 


0.001 


0.001 


2 


10-20-80 


23:59:51 


0.001 


0.000 


0.001 


0.001 


3 


10-20-80 


23:59:51 


0.002 


0.000 


0.002 


0.000 


4 


10-20-80 


23:59:51 


0.002 


0.000 


0.002 


0.000 


5 


10-20-80 


23:59:51 


0.002 


0.000 


0.002 


0.000 


6 


10-20-80 


23:59:51 


0.003 


0.000 


0.003 


0.000 


INDEX BUILT 












6 


10-20-80 


23:59:51 


0.004 


0.000 


0.004 


0.001 



KBUILD COMPLETE. 



KBUILD ERRCR MESSAGES 



In addition to the messages that are listed in Appendix A AMOk^ KBUILD 
will display one of the following messages during run-time if it gets 
into trouble. Some errors are fatal: these are always evidenced by 
the fact that KBUILD aborts after it reports than. In SOTie "fatal" 
errors files may be damaged, but in most cases, they are still useable, 
as indicated in the error message explanations that follow. 



W INVALID DIRECT ACCESS ENTRY NUMBER ~ RECORD NOT AIX»ED 

The user-supplied direct access record nunnber is an ASCII string, but 
is not legitimate if it contains non-nuneric characters. Also, the 
entry number may be less than or equal to 0, may not be a v^KDle number 
or may exceed nunber of records allocated. (Non-fatal) 



^ INVALID OUTPUT DATA RECORD LENGTH ~ RECORD NOT AKKD 

The output record length is an invalid ASCII string — that is, it 
contains non^iumeric characters. Also, the size specified might exceed 
the input record size. (Non-fatal) 



► THIS INDEX IS NOT EMPTY. EITHER ZERO THE INDEX OR DO NOT SPECIFY 
THIS KEY AS SORTED. 

KBUILD cannot add sorted data entries to any index subfile that already 
contains entries. (Non- fatal) 
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► INDEX BLOCK SIZE GREATER THAN MAXIMUM DEFAULT 

The value of RECLNT in KPARAM used in building the fffiUim utility is 
smaller than the RECLNT value used vi*ien "the file was created^ with 
CREATK. (Eatal) 



► UNABLE TO REACH BOTTOM INDEX LEVEL 

Couldn't locate last level index block — file is damaged. (Fatal) 

► CAN'T FIND PRIMARY KEY IN INDEX — RECORD NOT AIX)ED 

Occurs vdien adding secondary index entries. Ihe primary key value 
supplied by the user was not found in the primary index. (Non-fatal) 

^ INDEX 0: INVALID KEY ~ RECORD NOT ADEED 

Gould occur if the input file is sorted and an entry was out of order, 
or if a duplicate key value appeared for an index that doesn't permit 
dupl icates . (Non-fatal ) 



► mmx FULL ~ INPUT TERMINATED 

If the maximum number of entries in primary index is exceeded, KBUILD 
aborts. (E^tal — but file still okay) 



► INDEX index-no FULL — NO MCRE ENTRIES WILL BE AIDED TO IT 

Same as above, but occurs during building of a secondary index. 
Building of other indexes continues. (F^tal — but file still okay) 
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^ INDEX FULL — REMAINING RECORDS WILL BE DELETED 

Data records are added to the subfile first, in the order read in from 
the input file. Then the primary index entries are added, in sorted 
order, to point to them. KBUILD ran out of room in the primary index 
v*ien trying to add entries to point to those already in the data 
subfile and is forced to set the delete bit on in data subfile entries 
vAiose primary keys will not fit in the primary index. (Eatal — but 
file still okay) 



^ index! 0: ) KEY SEQUENCE ERROR — RECORD NOT ADDED 
|index-no : j 

A duplicate value was discovered for the primary key or for a secondary 
key that doesn't allow duplicates. (Non-fatal) 
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DELETING A MIDftS PILE 
(KIDDEL) 



INTRODUCTICN 

Ihis section covers the KIE»EL utility Which is the fastest method of 
destroyirg or zeroing (ranoving entries from) part or all of an 
existing MIDAS file. 



THE KIDDEL UTILITY 

The MIDAS KIDISIL utility performs the following functions: 

• Deletes an entire MIDAS file, including all index subfiles and 
data subfiles 

• Deletes one or more secondary index subfiles (completely) 

• Deletes "junk" (work files, etc.) left over from an aborted 
MPACK run (see Section 12) 

• Zeroes out (initializes) one or more secondary index subfiles 
(removes all entries therefrom) 

• Zeroes out, or initializes, all entries in the primary and 
secondary index subfiles, and all entries in the data subfile, 
if the file is a direct access MIDAS file 



Zero vs. Delete 

The KIDDEL dialog asks if you want to "delete" or "zero" a file's 
indexes. "The difference between delete ard zero is that delete gets 
rid of an entire index subfile, vrfiereas "zero" only deletes the entries 
and unused space in an index subfile. An initialized or "zeroed out" 
file looks exactly like the initial template created for the file with 
CREATK. 
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The KIEPEL Dialog 

Ihe KIDDEL dialog shows how to respond to each pranpt (prompts are 
nurriDered for convenience) : 



Prompt 

1. FILE NAME? 

2. DELETE INDEXES: 



3. ZERO INDEXES: 



Response 

Ehter pathname of MIDAS file to be KIDDELed. 

Biter one of the following: 

List of secondary indexes: nunbers of 
secondary index subfiles to be deleted. Use 
optional commas between ntanbers. 

ALL: kills entire file, deletes it from the 
UFD it resides in, and returns you to 
PRIMOS. 

JUNK; deletes residual "garbage" left after 
an aborted MPACK operation. 

NO[NE] : you want no index subfiles deleted, 
but instead want to zero one or more of 
thCTi. Dialog continues at step 3. 

Asked only if you entered "NCWE" to above 
prompt. You may enter one of the following: 

List of indexes: the nunbers of secondary 
index subfiles v*iose entries are to be 
deleted . 

ALL: zeroes all index subfiles and the data 
subfile. If a direct access file, the file 
is reinitialized. 

NONE: returns you without action to PRIMOS. 

Note 



It is not legal to enter "0" (primary index) in response to 
either prompt 2 or 3. If you want to delete or zero the 
primary index, you should use the "ALL" response. 



KIDDEL Example 

This example uses a version of the CUSTOMER file (created in Section 2) 
v*iich has been accessed by both PL/I and BASIC/VM programs. Several 
records have been deleted from the file by primary key, and the 
secondary key entries v*iich referenced these records still remain in 
the secondary index subfiles. KIDDEL is first used to remove entries 
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from the secondary indexes in the file. It is then used to zero all 
the index subfiles and finally, to delete one of the secondary index 
subfiles. 

The "usage" option of CREATK is used to find out how many entries are 

in the index siiafiles before and after KIDDEL is run. USAGE 

(abbreviated "u") was briefly mentioned in Section 2; See Section 12 
for more information on this and other options. 

Cbnments have been appended for explanatory purposes. 



OK, 

OK, kiddel 

[KIDDEL rev 17.6] 

FILE NAME? custaner 

EELETE INDEXES: none 

ZERO INDEXES: 1^ 

OK, 

OK, creatk 

[CREATK rev 17.6] 

MINIMUM OPTIONS? y^ 

FILE NAME? custcmer 
NEW FILE? no 

FUNCTICW? u 

INDEX? 

ENTRIES INDEXED: 
ENTRIES INSERTED: 
ENTRIES DELETED: 
TOTAL ENTRIES IN FILE: 



Get rid of entries in secondaries 



Check vhat's in the index subfiles 



LAST MODIFIED BY MIDAS REV. 17.6 

FUNCTION? u 

INDEX? JL 

ENTRIES INDEXED: 

ENTRIES INSERTED: 

ENTRIES DELETED: 
TOTAL ENTRIES IN FILE: 

LAST MCBIFIED BY MIDAS REV. 17.6 

FUNCTICN? u 

INDEX? 2 
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ENTOIES INDEXED: 

ENTRIES INSERTED: 

ENTRIES DELETED: 
TOTAL ENTRIES IN FILE: 

LAST MODIFIED BY MIDAS REV. 17.6 



FUNCTI»J? q 
OK, 

OK, 

OK, kiddel 

[KIDDEL rev 17.6] 

FILE NAME? customer 

raiLETE INDEXES : none 

ZERO INDEXES: all 
OK, creatk 
[CREATK rev 17.6] 

MINIMUM OPTIONS? ^s 

FILE NAME? customer 
NEW FILE? no 

FUNCTION? u 

INDEX? 

ENTRIES INDEXED: 
ENTRIES INSERTED: 
ENTRIES DELETED: 
TOTAL ENTRIES IN FILE: 



lb get rid off all index subfile 
and data subfile entries, zero 
everything with the ALL option: 











LAST MODIFIED BY MIDAS REV. 17.6 

FUNCTICN? u 

INDEX? 1 

ENTRIES INDEXED: 
ENTRIES INSERTED: 
ENTRIES DELETED: 
TOTAL ENTRIES IN FILE: 

LAST MODIFIED BY MIDAS REV. 17.6 

FUNCTICN? q 

OK, Everything is now gone. 
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OK/ To delete an index subfile, 

use the delete option: 
OK, kiddel 

[KIDDEL rev 17.6] 

FILE NftME? customer 

MLETE INDEXES: 2 
OK, creatk 
[CREATK rev 17.6] 

MINIMUM OPTIONS? ^s 

FILE NAME? cus toner 
NEW FILE? no 

FUNCTION? p 

INIEX NO.? 2 

INDEX DOES NOT EXIST 

INmX NO.? (CR) 

FUNCTION? q 
OK, 



KIDDEL Error Messages 

If the MIDAS file beir^ KIDDELed was created by a version of MIDftS 
earlier than Ftev 15, or if other file inccmpatibilities exist, the 
KIDDEL utility may return one of several error messages to the user's 
terminal during file processing. 

Some error messages are shared by several MIDAS utilities, so the user 
may also encounter them vhile using utilities other than KIDDEL. See 
^pendix A for a list of these error messages. 
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SECTION 5 
FILE ACCESS OVERVIEW 



INTRODUCTION 

This section is an overview of all the MIDAS file operations that can 
be performed in the various language interfaces. It surmarizes v*iich 
file access operations are available in each language interface and 
tells you vAiere to find more information. The next four sections 
explain how to add data to and retrieve data fran a MIDAS file using 
each of the language interfaces. The file created in Section 2 is used 
throughout subsequent sections to illustrate MIDAS file access. 

Once a simple template is set up, data must be added to create a data 
subfile. If you already have a sequential data file. Section 3 tells 
you how to go about "adding" it to the template. Tliere are several 
ways to do this, the most common being KBUILD. The KBUILD utility is 
completely documented in Section 3. 

As soon as the data subfile has been populated, (that is, v*ien it 
contains record entries) , information can be retrieved from the file 
using any of the keys defined for the file. Information retrieval, 
update, deletion etc., are all treated in each of the language 
interface sections. 



Fundamental Access Operations 

Accessing a MIDAS file usually involves these basic operations: 

• Opening a file for update and/or read access 

• Adding a record 

• Fbsitioning to a file record on any key 

• Rssitioning to a file record without key; record is 
automatically locked but not read 

• leading a record by any key (partial/full) 

• Reading next record in sequence 



October 1980 



SECTION 5 IDR4558 

• Reading next (sequential) record with the same key 

• LDcking a record with a read operation 

• Updating current record 

• Deleting current record 

• Deleting a record by a key 

• dosing the file 



MIDRS tecess in Five Languages 

Each language interface has a slightly different method of performing 
these operations. The FORTRAN interface is presented first, as it is 
the basis of all other MIDAS interface methods and presents the full 
range of MIDAS access capabilities. In addition, a section of this 
book is devoted to each of the language interfaces to make life easier 
for each language prograrnmer: 

Section Language 

Section 6 FORTRAN (FMA,F77) 

Section 7 CCBOL (Keyed index access only) 

Section 8 BASIC/VM 

Section 9 PL/I Subset G 

Section 10 RPGII 

Section 12 CCBOL (direct access only) (RELATIVE) 

Language Interface Routines and Statements 

Table 5-1 summarizes the possible MIDAS access functions and the 
routines and/or statements available to perform them in each language 
interface. Where an appropriate statement or routine does not exist to 
perform such an operation, the vvord "NO" appears. This table is just a 
summary and does not represent the vAiole scope of each language 
interface. Please refer to the indicated section for particulars on 
the language interface you're interested in. 
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T^le 5-1. Language Interface ftjutines 



Function 

POSITI(»I FILE and 
automatically LOCK 
RBCCRD: (without 
returning record) 

by primary 



by secondary 



CCBOL BASIC 



START 



POSITIC»1 1 
REWIND I 



START I position! 
JREWIND f 



RPG 



FCBTRAN PI/I 



CALC SETLL NO 



NO 



NO 



LOCATE with 
KEY option 

NO 



READ and LOCK 
RECORD: 



by primary key 


READ * 


READ 


PRIMKEY 
KEY 


CALC CHAIN 


LOCK$ 


READ with 
KEY option 


by secondary key 


READ * 


READ KEY 


NO 


LOCKS 


NO 


by partial key 


READ * 


PRIMKEY 
READIKEY 


NO 


LOCKS 


NO 


next record 


READ 
NEXT * 


READ SEQ 


Input Cycle 

or 
READ + 


NEXTS 
followed 
by LOCKS 


READ 


next with same 
key value 


READ 
NEXT * 


READ SAMEKEY 


NO 


NEXTS 
followed 
by LOCKS 


NO 



current record 



READ ** READ 



NO 



LOCKS 



NO 



READ without LOCK: 



READ *** NO 



NO 



NEXTS 
or 

FINDS 



NO 



* Record only locked file is open for I/O 

** Only after START or with KEY IS clause (RANDOM access) 

*** If file open for (WtfPUT (reading) only 

+ For indexed files declared as Primary (P) , Secondary (S) , or Demand (D) 
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Tdble 5-1. language Interface Routines (continued) 



Function C(BOL 

READ KEY: (read key 
associated with record) 

current key NO 



keyed on partial NO 

primary or secondary 



BASIC 



RFG 



FOR'TOAN PL/ 1 



READ KEY 



READ KEY 



NO 



NO 



FINDS 
FIND$ 



READ with 
KEYTO{var) 

NO 



READ SECONDARY 
EATA: 



NO 



NO 



NO 



FIND$ 



NO 



UPDAWREWRITE current 

data record REWRITE UPDATE 



Output 
Cycle 



UPDAT$ 



REWRITE 

[key 

optional] 



ADD: 



data record and 
keys by primary key 



WRITE ADD 



Output : 
AM) 



ADD1$ 



WRITE 



secondary index 
to a data record 



NO 



NO 



NO 



AED1$ 



NO 



DELETE: 



current data 
record 



EMELETE * NO 



NO 



DELET$ DELETE 

[no key] 



data record by 
primary key 



secondary index 
entry (only) 



UNLOCK record 
without update! 



DELETE REMOVE 



NO 



NO 



REMOVE 



NO 



NO 



NO 



NO 



DELET$ DELETE with 
KEY option 



DELET$ NO 
UPDAT$ NO 



* In SEQUENTIAL access, only if record already locked by a READ 
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Gaieral Changes 

The file-no argument, vAiicdi appears in all of the PORTRfiN 
subroutine calling sequences, can be set to any valiK the user 
desires. Currently the documentation infers that file-no should be 
set to 0. This argument is ignored completely by MIDftS and is 
being preserved only for compatibility. 
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SECTION 6 
THE FGRTRAN INTERFACE 



INTRODUCTION 

The FCKTRAN interface to MIDAS is a collection of user-callable 
routines that can be called from any program written in FORTRAN, PMA, 
PL/If and so forth. However, it only makes sense to use these routines 
in FCffffRAN and PMA, as all the other prograirming languages that support 
MIDAS have already incorporated these routines into their respective 
interfaces. Ihe FORTRAN/MIDAS interface package handles both 
keyed-index and direct access MIDAS files. The main emphasis of this 
section is on keyed-index access; therefore, this information is 
presented first, and is followed by pertinent direct access 
information. Background information on direct access MIDAS files, 
including a description of file structure and how to create a direct 
access tsnplate, is covered in Section 11. 



Which FORTRAN? 

The term " FORTRAN", as used in this section, refers to both FORTRAN IV 

QjlU l:Or\Ar«Ti>( iff uiic l^vw.^ iTT xittc ou^^a^l ucm vSju^J-vm^ \j3- \^a.txs *. wi\AA^rii.\ 

programming language. Both versions of FORTRAN handle MIDAS calls 
identically, and programs can be written in either language to access 
MIDAS files. Ohe should be careful of the differences between the tWD 
languages, however. There is no guarantee that all programs written 
and compiled under PIN will compile and run under F77. Par example, 
one of the coirmonly-encountered discrepancies between the twa involves 
variables declared as "INTEGER". FC«TAN IV assumes they are INTEGER*2 
and FORTRAN 77 assumes they are INTEGER* 4. Refer to The FCRTRAN 77 
Reference Guide for a suninary of the important differences between the 
two languages. All the programs shovm in this section were compiled 
without errors under h)oth compilers. 



Compile and load Sequence 

All FORTRAN programs that use MIDAS must have the MIDAS library VKDALB, 
included in the SEG load sequence, as shown in this example. User 
input is underlined to distinguish it from system output. 
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OK, FTO RRCX3RAM -64V 

0000 ERRORS [<.MAIN.>FTO-REV17.6] 

OK, SBG 

[SBG rev 17.6] 

# LCftP #PROGRAM 

$ LO B-PROGRAM 

$ LI VKDALB 

$ LI 

LOAD CCMPLETE 

$ SA 

$0" 

OK, 

The same sequence applies to programs written in FORTRAN 77; simply 
substitute "F77" for "FTO". AtJditional FOPTBfiN program requiranents 
are addressed under $INSERT Mnemonics later in this section. 



FC»^TRAN's Requirements 

All the other language interfaces sit on top of the FORTRAN interface, 
automatically taking care of all the subroutine-level file I/O, 
eliminating the need for the programmer to keep track of v*iat's 
actually going on "underneath." The FCHTRAN interface, however, 
requires the user to be concerned with explicit tasks like notifying 
MIDAS v*ien a file is opened and closed, permitting several users to 
access the same file simultaneously or denying multiple user access to 
that file, locking/unlocking a record, keeping track of the current 
record (see FILE ACCESS COTCEPTS, below) and monitoring file position 
relative to an index subfile. 



Why the "fasks are Necessary 

The special method of opening and closing files is part of the MIDAS 
concurrent process handler which regulates the simultaneous access of 
processes to a single MIDAS file. There are several methods of doing 
this, all of which are described in this section. The current record 
must be monitored by MIDAS in order to avoid errors like operating on 
the wrong record. lb keep track of current file position and of v^at 
the user is doing in a given file, MIDAS uses a 14-word array. While 
the entire array is not the user's responsibility, the user must know 
how to utilize certain parts of it. These tasks aren't at all 
difficult, although they may seem complicated at first. They are 
explained a bit at a time so you can see how they all fit together. 
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Sunmary of FCRTRAN Access Operations 

Below is a summary of the basic access operations available to the 
FORTRAN (and PMA) prograrmer. The subroutines that perform these 
operations are listed below, and are described fully later in this 
section. 



FORTRAN Access Operations 
and Oorresporejing Subroutines 



Operation 
Adding a record 

Adding a secondary index entry 
Closing a file 
Deleting a record 
Deleting an index entry 
Locking a record for updating 
Opening the file 
Etositioning the file by key 
Reading a record by key 
Reading duplicates 

Updating a record 



FIN Subroutine 
AODIS 
ADD1$ 

CLOSM$,NTFWI$ 
DELET$ 
DELET$ 
LOCK$ 

OPENM$,NTFm$ 
FIND$,NEXT$ 
FIND$,NEXT$ 
NEXr$ 

NEOT$,GnATA$ 
UPDAT$ 
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OPENING AND CLOSING MIDAS FILES 



like all FORTRAN files, MIDAS files must be explicitly opened and 
closed. There are two ways to open a file in the current version of 
MIDAS (this applies to versions stamped Rev. 17 and above): 

• Existing programs v*iich use SRCH$$ or TSRC$$ to open and close 
the file can be modified by making calls to NTF»1$, a routine 
that notifies MIDAS when a MIDAS file is opened and/or closed. 

• The OPENM$ subroutine can be used to perform the tasks of both 
SRCH$$ (or TSRC$$) and NTF!M$ in one step. 

In either case, opening the file associates it with a particular file 
unit, vAiich is in turn associated with the user number of the process 
which opened that file unit. 



Setting the READ/WRITE Lack 

The READ/WRITE lock on all MIDAS files should be set to 3 before they 
are accessed. See your Systan Administrator if there are any 
questions. This READ/WRITE lock setting allows a MIDAS file to be 
opened for writing and reading by more than one process at a time. 
This is part of MIDAS' s concurrent process handler, which is explained 
in Section 13 and ^pendix D. 



Requiranents for Existing Applications 

Existing FORTRAN afplication programs (written prior to Rev. 17) must 
be modified in order to operate with the current version of MIDAS. 
MIDAS must be notified v*ien a MIDAS file (segment directory) has been 
opened for processing. You can replace the existing file open/close 
routine (generally it's SRCH$$ or TSRC$$) with calls to OPENM$ and 
CLOSM$; alternatively, leave the existing open/close routine in place 
and insert calls to NTFYM$ after the file has been opened and before 
the file is to be closed. If desired, the user can completely disable 
concurrent process handling, thereby making no changes to existing 
application programs. This, however, will result in performance 
degradation. See Section 13 for details on disabling the present 
method of concurrency handling. 
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Benefits of "New" Method ; 0PE1W$, CLOSM$ and NTFM$ allow segments to 
be left open between calls, resulting in a great performance 
improvanent over the old method. (See Previous Concur rency-Handlir^ 
Methods , in Appendix D.) They also permit MIDAS' s concurrent process 
mechanism to vrork, v*iich allows more than one user to have the same 
segment subfile open for use. Kbwever, it prevents these processes 
from operating on the same record simultaneously. If you do not use 
either 0PE1!W$ and CLO£M$, or NTFYM$ and SRCH$$, the new concurrent 
process handling method will be disabled. The old methods of opening 
and closing files do not allow for file segments being left open 
between calls viAiich results in significant peformance degradation. 



Note 

Programs that use offline routines (documented in Section 14) 
should not use OPENM$/CLOSM$ or NTFYM$ to open MIDAS files. 
Use SRCH$$ or TSRC$$ instead. 



OPENM$: OPENING THE FILE 

OPENM$ is the MIDAS routine vAiich opens a MIDAS file (segment 
directory), associates it with a file unit, and notifies MIDAS that 
processir^ is about to begin on that particular file. MIDAS itself 
needs this information to keep track of all the processes interacting 
with a MIDAS file; without this "monitoring" system, MIDAS file 
integrity could be adversely affected by conflicting concurrent 
processes . 



OPENM$ Keys 

OPENM$ replaces direct calls to either of these PRIMCK file system 
routines: 

• SRCH$$, v*iich takes a filename argument 

• TSRC$$, v*iich takes a pathname or treename argunent 

These routines are responsible for opening a file and associating it 
with a PRIMOS file unit. OPENM$ requires the use of certain TSRC$$ or 
SRCH$$ keys, which tell PRIMOS whether a file is to be opened for 
reading, writing or both: 
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Key tetion 

K$GETU Opens file on an available PRIMOS file unit; should be 
used v*ien first opening the file from a program 

K$READ Opens file for reading only 

K$WRIT Opens file for writing only 

K$REWR Opens file for reading and writing 

Ihese keys are used in calling OPENM$ as shown below. 



0PEa4M$ Calling Sequence 

Ihe calling sequence of 0PE1*1$ is: 

CALL 0PENM$ (key, pathname, namlen, funit, status) 

The arguments, v^ich are all INTEGER*2, are: 

key Valid 0PENM$ access key: K$READ, K$WRIT, or K$RDWR, used 
optionally together with K$GETU (supplied by user) 

pathname Pathname (treename) of MIDAS file to be opened (supplied 
by user) 

namlen Length of pathname in characters (supplied by user) 

funit funit is the file unit on viiiich the file is to be opened 
(supplied by user); if K$GETU is specified instead, 
funit is returned as the file unit on vAiich the file was 
opened (returned by 0PEM$) 

status Error status (returned by 0PENM$) 





< 10001 

10001 

10002 

10003 



No error 

PR3M0S file system error (system-defined) 

Bad key 

Too many MIDAS files open: limit is 128 
(*Ihis is the MFILES argument in KPARAM 
file: see Section 15.) 



Specified file is not a 
directory 



MIDAS 



segment 
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CLOSM$: CLOSING TBE FILE 

The CL0S»1$ routine closes a MIDAS file (segment directory) opened on a 
specified file unit, and closes any of the subfiles v*iich MIDAS has 
opened during file access. 

CL0SM$ Calling Sequence 

The calling sequence of CLOSM$ is: 

CALL ClJOm$ (funit, status) 
The arguments (INTEGER*2) used in this call are: 

funit File unit on v*ich the MIDAS file is open (supplied by 
user) 

status Error status (returned by CLOSM$) 

No error 

> PRIMOS file system error (systan-defined) 

Using OPEm$ and CLOa^$ 

The following program segment could be used to open and close the MIDAS 
file created in Section 2: 

C Ifee OPENM$ to tell MIDAS v^'re 
C going to open and use this file 

CALL OPENMS (K$RDWR+K$GETU, 'CUSTOMER' ,8, FUNIT, STATUS) 



Process MIDAS file (with FIND$,AIE)1$ etc.) 



Close the file 

CALL CLOSM$( UNIT, STATUS) 



END 

In the above example, the K$GETU key tells PRIMOS to open the file 
CUSTOMER on any available file unit that is returned in FUNIT. STATUS 
returns an error code that tells \fl*iat kind of error, if any, was 
encountered upon opjening or closing the file. 
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NTFYM$: THE "NOTIFY MIDAS" ROUTINE 

The NTFYM$ routine informs MIDAS that a MIDAS file (segment directory) 
has been opened or is about to be closed by the user. It can generally 
be inserted into an existing program immediately after a call to SRCH$S 
is made to open the file and immediately before SRCH$$ is again called 
to close the file. 

A call to NTFYM$ after a MIDAS file has been opened tells MIDAS that it 
should leave open between MIDAS calls any of the file's segment 
subfiles opened during subsequent file access. A call to NTFW$ before 
a MIDAS file is closed tells MIDAS that it should close any of the 
file's segment subfiles that it has left open. If the MIDAS library 
has been customized to disable internal locking, a call to NTFYM$ has 
no effect. Users with existing applications may use NTFYM$ along with 
SRCH$$ or TSRC$$ (in lieu of OPENM$ and CLOSM$) . 



NTFYM$ Calling Sequence 

Ihe calling sequence is: 

CALL NTFli!M$ (key, unit, status) 

Ihe argunents (all INTEGER*2) used in this call are: 

key specifies whether the file has been opened or is about to 
be closed (supplied by user) 

1 - file has been opened 

2 - file is about to be closed 

unit File unit on vAiich the file is open (supplied by user) 
status Error status (returned by NTFW$) 
No error 

10001 Bad argument 

10002 Too many MIDAS files open simultaneously; 
occurs only if key is 1 (default limit = 128) 
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Use of NIFYM$ 

The following sample FCS^TRAN program opens the CUSTOMER file on a file 
unit obtained by using the K$GETU key. (See 0PEM>1$ Keys , above.) 
Assuming the call to NTFW$ is successful, the variable TYPE returns a 
code identifying the type of the file that was opened. If the file is 
indeed a MIDAS file, TYPE will be returned with a value of 2, 
indicating that the file is a SAM segment directory. (See The PRIM06 
Subroutines Reference Guide for more information.) The program calls 
NTFYM$ to notify MIDAS that it is ready to begin operations on a MIDAS 
file. The program also notifies MIDAS vAien processing is completed and 
then closes the file. 

C OPEN THE FILE 

CALL SRCH$$ (K$READ,' CUSTOMER', 8, K$GETU,TYPE, CODE) 

IF (CODE .NE. 0) GO TO 9000 /* ERROR ON CALL 

IF (TYPE .NE. 2) GO TO 9999 /* NOT A MIDAS FILE 

CALL NTFYM$(1,UNIT,C0DE) /* TELL MIDAS WE'RE READY 

IF {CCDE .NE. 0) GO TO 9002 /* HANDLE ERRO^ 

200 CaWINUE 



DO MID^ FILE K^CCESSIJSj (E.G. CALLS lO tINDS ETC.) 



CALL NTFYMS (2, UNIT, CODE) /* TELL MIDAS WE'RE DONE 

CALL SRCH$$ (K$CLOS,0,0,UNIT,TYPE,CODE) /* CLOSE FILE 



ETC. 

Ihe labels 9000, 9002, and 9999 refer to statements in the program (not 
shown here) that handle errors occurring on calls to SRCH$$ and NTFYM$. 
Note that if we'd used a pathname for the MIDAS file instead of a 
filename, TSRC$$ WDuld have been used in place of SRCH$$. 
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FILE ACCESS CCNCEPTS 

MIDAS file access at the FCRTRAN call -inter face level involves some 
important concepts v*iich should be understood if you want to write and 
debi:^ a program successfully. These concepts include: 

• The current record 

• Record locking 

• The conmunications array 

• $ INSERT files 

• The MIDAS flags 

The Current Record 

The current record can be thought of as that record in the file to 
\«*iich the file pointer is presently positioned. Usually, this occurs 
as a result of a read (find) operation. Some MIDAS calls need to know 
v*iich record is the current record so that the operation is performed 
on the right one. Fbr example, if a record is being read, it is the 
current record. After the read operation is complete, that "current 
record" location is stored away so the next operation knows v*iich 
record to act on should that be necessary. If the subsequent operation 
is a "read next" operation, the file handler has to check where the 
current file position is so it can read the proper record. Ihe proper 
record is the one after the record just read, so it becomes the current 
record. If, however, the subsequent operation is a call to Fp]D$, 
MIDAS doesn't care which record is current because it must do an index 
search to find the desired record anyway. 

This current record position information is stored in 14-word array 
supplied on each MIDAS call. It is constantly updated and checked by 
MIDAS, and is used to communicate index location, file position and 
current record location between MIDAS and the user. Consequently, it 
is called the MIDAS "conmunications array," although it is commonly 
referred to simply as "the array" throughout this book. 

Ihe Communications Array 

The communications array is used by MIDAS to keep track of the current 
file position once a MIDAS file has been opened for access. The array 
stores several items, including the address of the current record, the 
current position in the index subfile, an indication of whether or not 
the last record was found, the word number of the located entry in the 
index subfile, and the data record address. The size of the array is 
14 words, but only the first five are important in the basic operations 
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dealt with here. The array is one of the arguments used in the calling 
sequences of most FORTRAN/MIDAS file access subroutines, so you'll be 
seeing a lot of it throughout this section. 

Record Locking 

In order to update a record, it is necessary to lock that record for 
exclusive use. This prevents anyone else from attempting to read or 
change the record v*ile you are changing it. Ihe other language 
interfaces to MIDAS perform locking automatically; the method of doing 
so varies in each one. Oily FORTRAN requires that an explicit lock 
action be taken by calling a special subroutine, LOCK$, before an 
update operation can occur. Record locking, however, does not entirely 
eliminate the possibility of concurrency errors because a locked record 
can be deleted by another user. 

The Array Fbrmat : From the user's standpoint, only the first five 
words of the array are really important. T^ble 6-1 describes the first 
five wards of the array as implonented for keyed-index access (access 
to keyed-index MIDAS files) . The description includes v*iat each word 
indicates and the meaning of the important bits in each word. The 
format of the array as used in direct access is shown in T^ble 6-2. 
The complete format of the array is discussed in Section 13. 

Qily the first word of the keyed-index access array can be modified by 
the user; the others are taken care of by MIDAS and return information 
that may or may not be important to your application. 

Table 6-1. Keyed-Index Access Array Format 
Ward Number Describes 

Wsrd 1 When supplied by user, can be 0, 1, 

or -1 (see below) ; viien returned by 
MIDAS, contains array state code 

Wards 2-4 Current position in index subfile 

(index entry address) 

Vford 2, bits 1-8 Ehtry number 

Ward 2, bits 9-16 Segment file number 

Wards 3-4 (32 bits) Ward offset of index subfile block 

Wsrd 5 Hash value (based on current key 

value) 
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Mbrd 1; Input Value ; The only word in the array that can be modified 
by the user is vgord 1. It can be set by the user to a value of 1, 0, 
or -1. Any other value produces an error on any call in v*iich that 
array is used. If set to or 1, MIDAS is told to use the current 
array contents on this call. If set to -1, MIDAS is told to ignore the 
array contents. 

Wbrd 1; Output Value ; The first word in the array is always used by 
MIDAS to return a completion code after an operation has finished. If 
set to or 1, the array contents are valid, and no error was flagged 
on the last call. If there was an error on the last call, word 1 has a 
value greater than 1 corresponding to some MIDAS error condition code, 
^perrfix A contains a complete list of MIDAS error codes. 

The Direct Access Array 

Ihe direct access array format differs slightly from the one used in 
keyed-index access. Ihe user must supply values for words 2, 3 and 4 
of the array on some calls. It is important to supply the proper 
values for each word of the array vAien processing direct access MIDAS 
files. 

Table 6-2. Direct Access Array Format 
Wbrd No. Setting Meaning 

1 or 1 Use array contents (supplied by user) 

2 entry size Ehtry length is the primary key length 
(in words) in words, plus data record length 

in words, plus 2 words 
(supplied by user) 

3-4 record number A single-precision (REAL*4) 

floating-point record number 
(supplied by user) 

5_14 Same as for keyed-index access 



$INSERT Mnemonics 

Another of the concepts peculiar to the FORTRAN interface is the 
$INSERT file SYSCOM>PARM.K. It contains a host of parameters used by 
MIDAS in the interface FORTRAN subroutines and must be inserted in each 
FORTRAN program that uses MIDAS. Put the statement; 

$INSERT SySCOM>PARM.K 

at the beginning of your programs. The $ INSERT statement must begin in 
column 1. Most of the parameters in the PARM.K file v*iich you are 
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likely to encounter are described later under Ihe MIDftS Flags . 

Another file the user will need to insert at the beginnir^ of a FORTOAN 
program is the SYSCCM>KEYS.F file vrfiich contains declarations for all 
the keys used by the FCHTRAN-MIDAS interface subroutines. Use the 
statsnent : 

$INSERT SYSCCM>KEYS.F 

at the beginning of all your FORTRAN programs. PMA programmers should 
use the file SysCCiM>KEYS.P instead. 



The MIDAS Flags 

MIDAS has a special set of flag values v*iich can be set in each of the 
various subroutine calls to tell MIDAS what options are to be used for 
that call. Cations are specified with a set of flag names which are 
defined in the insert file SYSCOM>PARM.K. The flag names correspond to 
single bits of a one-word parameter called flags , vi*iich is passed to 
MIDAS by the user in each subroutine call . Table 6-3 lists each flag 
name and the bit to v^iich it corresponds. lb use the flag options, 
ccsnpile your programs with the statement: 

$ INSERT SYSCOM>PARM.K 

Each flag bit is set off by default; you set certain ones on before a 
call, depending on \n*iat you want to do on that particular call. Tb set 
a flag on, all you have to do is specify the name of that flag in an 
assignment statement or in place of the flags argument on the actual 
call. MIDAS takes care of the rest. Ebr example: 

FLAGS = FL$FST + FL$RET 

As a result of this assignment, the octal values of the two flags 
FL$FST and FL$RET are added together, and the result, a single octal 
value, determines vi*iich bits are set off and v*iich are set on in the 
flag word. Don't vrerry about the octal values because all the bits are 
initialized for you in the PARM.K file. The bit settings indicate the 
actions to be taken on the call. 

All the flag names, the bits to vdiich they correspond, their octal 
values, their meanings vdien set off or on, and the subroutine calls in 
v*iich they can be used, are listed in Table 6-3. 
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Table 6-3. 


MIDAS F] 


Bit No. 


Name 


Setting 


1. 


FL$USE 


ON 




(: 100000) 


OFF 


2. 


FL$RET 


ON 




(: 40000) 


OFF 


3. 


FL$KEY 
(: 20000) 


ON 
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OFF 



FL$BIT 



(:10000) 



FL$PIW 
(:4000) 



ON 



OFF 



ON 



OFF 



Can Be 
Used In 

All calls 



Meaning 

Use current copy of 

array. 

Don't use current copy 

of array. 

Return entire array for All calls 
use on subsequent calls. 
Return ccanpletion code 
only, in array(l) . 

Qi calls to FIND$, NEXT$ All calls 

and LOCK$, returns 

primary key with data 

record. Ch calls 

to AIX)1$, tells MIDAS 

not to make its own 

copy of the primary key 

to store in data record. 

Used only if primary key 

is first field in data 

record . 

Ch calls to FIND$, NEXT$ 

and LOCK$, does not return 

primary key in data buffer. 

In ADD1$, tells MIDAS to 

store a copy of primary 

key in each data subfile 

record . 

Call specifies key size FIND$ 
in bits, if key is a bit and 
string, or in bytes, if NEXT$ 
it is an ASCII key. 
Call specifies key size 
in words (default) . 

Position to next index FIND$ 

entry greater than or and 

equal to current or user- NEXT$ 

supplied entry. 

Fbsition to next index entry 

only if it matches current 

or user-supplied key. 
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6. 



FL$UKY 
(:2000) 



CXJ Update user-supplied 

key field with version 
stored in the file- 
Useful in partial key 
searches . 

OFF Don't update user-supplied 
key field. 



7. 



8. 



9. 



FL$SEC 



(:1000) 



FL$ULK 
(:400) 



FL$FST 
(:200) 



101. 



FL$N)Cr 
(:100) 



11. 



FL$PRE 
(:40) 



FIND 

and 

NEXT$ 



ON 


Return secondary data 


FIND$ 




instead of data record. 


and 


OFF 


Return data record read 
from data subfile. 


NEXT$ 


ON 


Unlock data entry 


UPDAT$ 




only — don't update it. 


only 


OFF 


Update data entry 
and unlock it. 




ON 


Fbsition to first 


FIND$, 




index entry in subfile. 


LOCKS, 


OFF 


BDSition to first entry 


and 




that matches current 


NEXT$ 



entry or user-supplied 
key value. 

Oti Position to next index 

entry greater than 
current entry or user- 
supplied key value. 

CFF Position to next index 

entry that matches current 
entry or user-supplied 
key value. 

CN RDsition to index entry 
just prior to current 
index entry or user- 
supplied key value. 

OFF Position to index entry 

that matches the current or 
user-supplied key value. 



PTMrK;; 

and 
NEXT$ 



FIND$ 

and 

NEXT$ 



Note 



Bits 12-16 of the flags parameter must be 
setting, at all times. Leave them alone. 



set to 0, the default 
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Order of Precedence ; When specified in combination, certain flags have 
precedence over others. The priority order is: 



• FL$FST 

• FL$NXT 

• FL$P[W 

• FL$PRE 

Cbserve that certain combinations of flags are simply not sensible: 
for example, FL$NXT and FL$PRE. Although meanings are given for each 
flag v*ien set off, the actual action taken on any given call is 
dictated by the ccwibination of keys set on, which may, in fact, 
override the defaults. 



TOE FORTRAN/MIEAS INTERFACE SUBROUTINES 

Ihere are seven FORTRAN subroutines that can be called directly by the 
FORTRAN programner in accessing a MIDAS file; they are used 
(transparently to the user) by all the other language interfaces. Most 
of these subroutines share the same calling sequence, viiich makes it 
easier to learn how to use them. They're listed below by function: 



Function 



Subroutine 



Adds a data record ADD1$ 

Adds a secondary index entry AID1$ 

Deletes a data entry or secondary index entry Effi;LET$ 



Finds a data entry by any key 

Finds the next data entry via an index 

Locks a data entry for update 

Reads data entries in order stored 
(lAiysically) 

l^ates a data entry 



FIND$ 
NEXT 
LOCK$ 
GDATA$ 

UPDAT$ 
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User-Supplied Information 

Ihe MIDAS access subroutines (AED1$, PIND$, LOCK$, BELET$, NEXT$ and 
UPDAT$) use essentially the same calling sequence. The variables used 
in this calling sequence pass the following information along to MIDAS: 

• The file unit nuntoer on viiich the MIDAS file is open 

• The size of the data record buffer: used for data added to or 
returned from the data subfile 

• The size of the primary key buffer 

• Ihe MIDAS cotrmunications array 

• The flag argument specifying the options to be used in the call 
(see below) 

• A program label indicating the alternate return to be taken in 
the event of an error: set to if no alternate return exists 

• The access method to be used (keyed-index or direct access) 

• The type of index subfile to be used (primary or secondary) 

« Ihe length of the data to be transferred (except in DELETS 
calls) 

• The length of the key to be used in partial key access 
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General Calling Sequence 

The general format of the calling sequence for the six data access 
routines mentioned above is: 



CALL routine (funit, buffer, key, array, flags, altrtn, index, 
file-no, bufsiz, keysiz) 

Specifies 

Che of these six routines: 

MJD1$, DELET$, FIND$, LOCK$, NEXT$ 

or UPDAT$ 

The file unit on v*iich the MIEAS file 
is open 

The i»8l5>i|#tW data record buffer 
into v*iich data is read or from 
v*iich it is written to the file 

The key value to be used on call 



Ihe communications array v*iich holds 
current record and index position 
information: also returns 
status codes after each call 

The flag ward specifying options 
for this call : see below 

Label in program of alternate return 
to be taken if an error occurs (set to 
if no alternate return exists) 

Ihe access method to be used, (keyed- 
index or direct access) and vAiich 
index to use if not direct access 

Obsolete: set to 



Argument 


Data Type 


routine 


character 


funit 


integer 
(short) 


buffer 


integer 
(short) 


key 


integer 
(short) 


array 


integer 
(short) 


flags 


integer 
(short) 


altrtn 


integer 
(short) 


index 


integer 
(short) 


file-no 


integer 
(short) 


bufsiz 


integer 
(short) 



keysiz 



integer 
(short) 



Ihe length of the data to be 
transferred to/from file 
(except in calls to DELET$) : 
set at if full data entry is 
being transferred 

The length of the key to be 
used in partial key access 
(used with FIND$ and NEXT$ only) 






//k 
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"Optional" Argisnents ; The arguments for which the user may supply a 
instead of another value, and their respective meanings vi*ien set to 
are: 

Argument Default 

altrtn There is no alternate return for handling errors on 
this call 

file-no Obsolete — maintained for compatibility 

bufsiz Default data subfile entry length (stored in file) 

keysiz Defaults to key length specified in file: can be set 

at if full key is being used 

Note 

Another data access subroutine, GDATA$, v*iich is used for 
sequential retrieval of entries in the data subfile, does not 
use the general calling sequence just described. Its 
particular calling sequence and function are described later in 
this section. 



An51$ 

The AH)1$ routine is used to add primary index entries and data subfile 
entries to keyed-index and direct access MIDAS files. It also adds 
secondary index entries (and optional secondary data) to files that 
have secondary indexes. During an add (as in all file operations) , the 
file is effectively locked to other users to prevent unnecessary 
complications. 



Keyed-Index Adds 

Records can only be added to a MIDAS file v*ien accompanied by a primary 
key value. Similarly, a secondary key value can only be added if the 
record v*iich it will reference already exists in the data subfile and 
is referenced by a primary index entry. Secondary index entries are 
always added separately from the primary index and data entries. 
Generally, records and the keys associated with them are added in this 
sequence : 
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1, First, make a call to AIX>1$, with FL$RET in flags set on, to 
add a data entry and its primary key value. 

2. Make a separate call to AIDIS, with FL$USE set in flags, to add 
a secondary index entry for this record. 

You can also add secondary index entries for an existing data subfile 
record at a later time, in either of tvro ways. The first method is to 
supply the primary key value in buffer and set index and key to the 
desired secondary index number and value respectively on a call to 
AED1$. In the second method, the record must first be located by 
primary key (with a FIND$ or NEXT$ call) . The array must be returned 
by this call so that the call to AED1$ will be able to use it. index 
and key must be set to the index subfile number and value on the call 
to AnDl$. 



Aroi$ Calling Sequence 

The calling sequence uses the general format shown earlier: 

CALL AIX)1$ (funit, buffer, key, array, flags, altrtn, index, 
file-no, bufsiz, keysiz) 

Some of the arguments have meanings peculiar to AnDl$. They are 
explained in Table 6-4. 

Index Values ; The irxiex argument indicates v*iether the add is being 
performed on a direct access file or a keyed-index file. It also tells 
v*iether a primary or secondary index entry is to be processed on this 
call. Here is a suranary of the values for the index argument: 

Value for Index MeanirKf 

Primary index 

1-17 Secondary index 

-1 Direct access 

When index is 0, the data entry information to be added to the data 
subfile must be supplied in buffer. If you are storing keys in the 
data, be sure to incude all - key values in buffer . When adding 
secondary indexes, index should be a number from 1 to 17, the 
corresponding primary key must be specified as the first item in the 
buffer; the secondary key value must be specified in full in the key 
argument . 
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On pages 6-21 and 6-31, the argament file-no was mistakenly emitted 
from the eurguroait explanation list. Please insert the following in 
between the index and bufsiz arguments on these pages: 

file-no Set this to 0: cteolete. 
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'teble 6-4. ADD$1 Arguments 



Argument 
funit 
buffer 



key 

array 
flags 

altrtn 

index 



fjLL'-A/6 



^€-e 



keysiz 



Meaning 

The file unit on v*iich the MIDAS file is opened. 

Qi a data entry add, it contains the data subfile 
record. If ke^^ are being stored in the data record, 
include all key values in buffer as well. Cn a 
secondary index add without FL$USE set, buffer 
contains the primary key value followed by optional 
secondary data. 

Must contain full primary key value on a data record 
add; contains full secondary key value on a 
secondary index add. 

Ihe communications array. 

The flags options for calls to AID1$ are shown in 
Table 6-5. 

Statement number of alternate return to be taken in 
event of error; supply if no alternate return. 

Indicates access method and index subfile to use: 

= primary index 

1-17 = secondary index 

-1 = direct access 

Length of data to be added to subfile from buffer . 
If bufsiz = and index = 0, MIDAS adds data from 
buffer to data subfile, taking only the number of 
words it needs to match the record size defined for 
the MIDAS file during CREATK. If index > 0, adds 
secondary data from buffer to indicated index 
subfile, if secondary data is supported for that 
index. If bufsiz is less than data record size or is 
less than key size plus secondary data, only that 
part of buffer will be used. Ihe rest of data 
subfile or secondary data entry is zero-filled. In 
general, specify for fixed-length records: for 
files with variable-length records, specify length of 
data to be written to file. 

Set to (ignored). 
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Table 6-5. Flags for AIX)1$ 



Flag Meaning 

FL$USE ; When set on, uses contents of array from previous 
call — used on calls to add secondary index entries. 
Set off v*ien adding primary index entries or secondary 
index entries v*ien FL$USE is off. 

FL$RET ; When set on, returns array contents from this call (set 
only on calls to add data records) . 

FL$KEY ; When set on, tells MIDPS not to store its own copy of 
the primary key with each data subfile record; see 
Redundant Primary Keys, below. 
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Heuunueiiit rTJ.mai.y Acyo 

MIDAS always stores its owi copy of the primary key with each entry in 
the data subfile. Wien an entry is returned from the data subfile, 
this primary key value is not returned unless specifically requested by 
the user. HDwever, if keys are being stored in the data record (by the 
user) , it is not necessary to have an extra copy of the primary key, as 
long as the user's copy of the primary key appears in the beginning of 
the data record, lb eliminate redundant copies of the primary key, set 
FL$KEY on in FLAGS for all AnDl$ calls that add data subfile entries. 
Remember, this option should be used only if the primary key is the 
first field in the data subfile record. 



Adding Data Records 

When adding primary index and data entries, the full primary key value 
associated with the record to be added should be placed in key. The 
information to be added to the data subfile is placed in buffer . The 
length of this entry must be supplied in bufsiz . For keyed-index MIDAS 
files with fixed-length records, bufsiz should be set to 0; for 
variable-length records, set bufsiz to the length of the data entry (in 
words). If there are secondary indexes in this file, the array should 
be returned (set the FL$RET flag on in flags ) for use in subsequent 
calls to AIDIS. 

Note 

When adding entries to a MIDAS file with ADD1$, the full key 
value must always be supplied in the key argument. Partial key 
values are illegal . Ihe argument keysiz is therefore ignored 
and can be specified as if desired. Consequently, bit 4 
(FL$BIT) of flags is not relevant in calls to AM)1$. 



Adding Secondary Index Entries 

When adding secondary index values, the user must provide MIDAS with 
this information: 

• Secondary index number (in index) 

• Secondary key value (in key) 

• Primary key value — must either be in first part of buffer or 
FL$USE must be set to use a valid copy of array. The array is 
valid only if returned by an immediately prior call in v\*iich the 
desired key value was used and/or returned . 

• Secondary data (optional — supplied in buffer , following 
primary key value) 
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The full primary key value is always supplied as the first field in 
buffer , if FL$USE is not indicated. Any secondary data information 
should be included after the primary key in the buffer argument. 

Duplicate secondary key entries are supported only for those index 
subfiles v*iich were created with duplicate status during CREATK. An 
attempt to add duplicate entries to a secondary index that does not 
support them results in an error and the failure of the add operation. 

Typical Scenario ; If you want to add all secondary irKlex entries for 
a particular data subfile entry immediately after you've added the 
primary key and the data entry, here's the typical sequence of events 
you'd follow: 

1. Set FL$RET in flags on the AH)1$ call vhen adding the primary 
index and data entry. 

2. After the above call, set FL$USE in flags if you have one or 
more secondary index entries to add. 

3. Set index to the appropriate index subfile number (1 -17) . 

4. If a valid array exists from a previous call (see Mding 
Secondary Index Ehtries above) , simply set FL$USE. Or, if the 
array is not valid, put the primary key value of this record in 
the first part of buffer ♦ This won't be necessary if you store 
keys (in order) in the data record because you will already 
have put the primary key value in buffer (1) on the previous 
call. 

5. Put any secondary data for this index entry in buffer, 
iirmediately following the primary key value. 

6. Set key to the full secondary key value you want stored in the 
index subfile. 

7. Make the call to ADD1$ to add this secondary index entry. 

8. Repeat steps 2-7 for each secondary index entry to be added 
for this record. 
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The following program adds entries to the MIDAS file CUSTOMER (set up 
in Section 2) . It is an interactive program intended for on-line data 
entry. Ihe program first asks the user for a primary key value, then 
asks if there are any secondary key values to be added for this record. 
After key values have been accepted, it asks for the non-key portion of 
the data record to be stored in the index subfile. In this 
application, all keys are being stored in the data record, and the 
primary key is the first field in the data record. If desired, we 
could use the FL$KEY option on each add so that MIDAS will use the data 
record's copy of the primary key instead of making its own copy of this 
key. However, we wDuld always have to set FL$KEY in calls to FIND$ or 
NEXT$ in order to get the primary key returned with the data record if 
we chose this option. Instead, FL$KEy is set off in this program so 
the full data record is always returned. 

C PjyO PROGRAM FOR. CUSTOMER FILE 

C 

C THIS PROGRAM ADDS ENTRIES TO THE CUSTOMER FILE BY ASKING THE 

C USER FCR KEY VALUES AND DATA RECORD VALUES. 

C THE KEYS ARE STORED IN THE DATA RECORD. 

C 

$ INSERT SYSCC»1>KEYS.F 

$INSERT SYSCC]M>PARM.K 

C DECLARATKaaS 

C Garden variety call parameters 

INTBGER*2 ARRAY (14) , INDEX, FUNIT, BUFFER (35) , STATUS, FLAGS 

INTBGER*2 KEY(13) ,BUFSIZ,KEYSIZ,CODE 
C KEY IS MAX OF 13 WORDS (SEC KEY01) 
C 

INTHGER*2 ANSWER, /* YES OR NO 

* I, /* LOOP INISX 

* PKEY(3) , /* PRIMARY KEY 

* SKEY1(13), /* SEC. KEY01 

* SKEY2(2), /* SEC. KEY02 

* DATA (17) /* JUST DATA PART 
LOGICAL *2 SWITCH (2) /* TELLS WHEN WE 

C HAVE SECONDARY KEYS TO ADD FOR AN ENTOY 
C SET SWITCH (1) C»J IF WE HAVE ENTRY FOR SEC KEY01 
C SET SWITCH(2) CW IF WE HAVE ENTOY FCB SEC KEY02 
C 

C EQUIVALENCE KEYS AND DATA TO PARTS OF BUFFER 
C SO THAT ALL KEY VALUES WILL BE STORED WITH RECCMD 
EQUIVALENCE ( BUFFER ( 1 ) , PKEY ( 1 ) ) , 

* (BUFFER(4),SKEY1(1)), 

* (BUFFER(17) ,SKEY2(1) ) , 

* (BUFF£H<19),DATAfl)) 
C 

aVITCH(l) = .FALSE. /* SET OFF INITIALLY 

SWITCH (2) = .FALSE. 
C OPEN FILE 
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10 CALL 0PE3^$(K$REWR+K$GETU, 'CUSTOMER', 8, FUNIT, STATUS) 

IF (STATUS .NE. 0) GO TO 100 /* ERROR 

G 
20 CALL TNOUAC ENTER PRIMARY KEY VALUE: ',25) 

READ(1,2222)PKEY 
C 

C ASK IF THERE ARE SECOCARIES TO AM) 

30 CALL TOOUACANY SEC(M]ARIES TO ADD FOR THIS RECORD?' ,40) 

READ( 1,1111) ANSWER 

IF(ANSWER .EQ. 'N') GO TO 50 
C ELSE GO Oti 
C 
35 CALL TNOUAC ENTER INDEX NO.: ',17) 

READ (1,6666) INDEX 

CALL TNOUAC ENTER KEY VALUE: ',17) 

IF (INDEX .EQ. 2) GO TO 40 

READ (1,4444) SKEYl 

SWITCH(l) = .TRUE. 

GO TO 45 
40 READ(1,5555)SKEY2 

SWITCH(2) = .TRUE. /* ENTRY FCS^ INDEX 02 

45 CALL TOOUA( ' MO^E? ' , 5) 

READ (1,1111) ANSWER 

IF(ANSWER .EQ. 'Y') GO TO 35 
C ELSE GO OJ 

C 
50 CALL TNOUAC ENTER DATA RECCM) (NON-KEY) INFO: ', 34) 

READ( 1,3333) DATA 
C SET UP FLAGS AND OTHER ARCS FCR CALL TO AI»1$ 

INDEX = 

FLAGS = FL$RET 
60 CALL AnDl$(FWIT, BUFFER, K(EY, ARRAY, FLAGS, $200, INDEX, 0,0,0) 

C 

IF( .NOT. SWITCH(l)) GO TO 90 /* NO KEY01 ENTRY 

C ELSE ADD ENTRY TO INDEX SUBFILE 01 
C 
75 FLAGS = FL$USE + FL$RET /* USE ARRAY 

CALL AnDl$(FUNIT,BUFFER,SKEYl,ARRAY,FLAGS,$200,l,0,0,0) 

C 

80 IF( .NOT. a^ITCH(2)) GO TO 90 /* EJJTRY F(M INDEX 02 ? 

C IF SO, ADD ENTOY FOR INDEX 02, RE-USING FLAGS SETTING 

CALL ADD1$ (FUNIT, BUFFER, SKEY2, ARRAY, FLAGS, $200, 2,0, 0, 0) 
C SEE IF WE'RE DONE 
90 CALL TNOUAC READY TO QUIT? (Y OR N)',23) 

READ (1,1111) ANSWER 

IF(ANSWER .EQ. 'N') GO TO 20 
C ELSE GET OUT 

GO TO 444 /* CLOSE FILE 

C FORMATS 
C 

1111 FORMAT (A2) /* ANSWER 

2222 FORMAT (6A2) /* PKEY 

3333 FORMAT (34A2) /* DATA 

4444 FORMAT (26A2) /* SKEYl 
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5555 FORMAT (4A2) /* SKEY2 

6666 FORMAT(Il) /* index 

C 

C 

C ERRCR HANDLERS 

100 CALL TNOUAC ERROR W OPEN: STATUS IS: ',24) 

CALL TODEC( STATUS) 

GO TO 444 
200 CALL TNOU ( ' ERROR CN AED' , 12) 

CALL 1NCXJA( ' INDEX IS: ' , 10) 

CALL TODEC( INDEX) 

CALL TOSIL 

CALL TNOUAC ARRAY (1) IS: ',13) 

CALL TODEC ( ARRAY (1)) 

CALL TOIL 

GO Ta 20 
444 CALL CLOSM$ ( FUNIT, STATUS) 
555 CALL EXIT 

END 

Here is some sample output from a terminal session using the program 
just listed: 

OK, SEG #ADD 

ENTER PRIMARY KEY VALUE: 2194G 

AUY SECONE^RIES TO ADD FOR THIS RECCSffi? Y 

ENTER INDEX NO. : j^ ~ 

ENTER KEY VALUE: SPECTROGRAPHICS 

M0RE7Y 

ENTER INDEX NO. : 2 

ENTER KEY VALUE: NWO^ 

M(»E?N 

ENTER DATA RECORD (NON-KEY) INFO: PORTLAND 

READY TO QUIT? (Y OR N) N 

ENTER PRIMARY KEY VALUE: 4056S 

ANY SECONDARIES TO ADD FOR THIS RECORD? Y 

ENTER INDEX NO. : j. ~ 

ENTER KEY VALUE: EASTERN GRAPHICS 

MORE?Y ' 

ENTER INDEX NO. : 2 

ENTER KEY VALUE: NECN 

MORE?N 

ENTER DATA RECORD (NCW-KEY) INFO: OLD SAYBROOK 

It is possible to add just primary key and data entries to the file 
using this program. Secondary index entries can then be added at later 
time, but the program wuld have to be modified to allow a FIND$ 
operation on a primary or secondary key value first, with FL$RET set. 
Then the array could be used on an AE»1$ call to add the secondary 
index entry. 
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Note 

Since primary index and data entries are added separately frcan 
secondary index entries, there is no guarantee that a record 
for v*iich you are in the process of adding secondary index 
entries cannot be deleted by another user before the current 
AM)1$ operation is complete. Files viiich are prone to 
multi-user access should be protected in some way, perhaps by 
another "single-threading" mechanian, much like that enforced 
by the MIDAS lock. 

Array Word Values 

The MIDAS array may return one of the following codes or values in vord 
1 after a call to AE01$: 

Value/Code Meaning 

Successful completion of call 

1 Successful completion: there are 
duplicates for this index (okay) 

7 No entry exists with supplied 

primary index value 

12 Attempt to add duplicates to a 

primary index or to a secondary index 
that doesn't allow them 

Others See Appendix A for a list 
of MIDAS error codes 



Direct Access Adds 

In direct access files, the user must set the index value to -1 in all 
calls to AnDl$ that add data entries, lb add secondary index entries, 
set index as described above. 'This indicates to MIDAS that the file is 
configured for direct access and that the user will be supplying a 
unique floating-point record number for each record added, in addition 
to a primary key value. The record number and the primary key can be 
the same, if desired (it's just a bit redundant). Remember that the 
record number does not have to be defined as a key during template 
creation because MIDAS takes care of storing the numbers. 
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In each call to ArS)l$, the user must provide: 

• A primary key value (in key) 

• A floating-point data entry number (in vords 3 and 4 of the 
array ) 

• The data entry size (in datasiz ) 

The data entry size is equal to the key length (rounded up, in words) 
plus the data length (in words) plus 2. Make sure you supply the 
correct data entry size every time. 

The Array ; The array format for direct access calls is shown earlier 
in Table 6-2. The contents of the first four words of the array in 
direct access calls to A1X)1$ are: 

• Wbrd 1 : Condition code (0 or 1) 

• Wbrd 2 : Data entry size (key size + data lerqth + 2) 

• Wbrds 3-4 ; Ehtry number (record number) in REAL*4 format 

If an entry already exists with the supplied record number, MIDAS 
places the new record into an overflow area. This will not happen 
however, if the primary key is defined as the record number because no 
duplicates are allowed for any primary key. 



READING A MIDAS FILE 

There is no "read" subroutine in the MIDAS-FCFTRAN call interface, but 
FIND$ and NEXT$ provide the same service. At the FORTRAN call level, 
there are three types of read operations possible: 

1. Keyed reads , by primary or secondary key, or by record number 
using FIND$ and NEXT$ 

2. Sequential reads , by primary or secondary key, or by record 
number — using NEXT$ 

3. Sequential data subfile reads , using GDATA$ to return records 
in physical order stored 

These three types of reads are discussed relative to the FINDS, NEXT$ 
and GDATA$ subroutines. Conceptually, FIND$ performs keyed or random 
reads. NEXT$ can do both keyed and sequential reads, v*iile GDATA$ 
performs only sequential reads. 
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Note 

Some of the other language interfaces automatically lock a 
record upon reading it. ftjwever, in the FORTRAN interface, 
none of the data retrieval routines locks a record upon 
positioning to it. The only way to explicitly lock a record is 
to use LOCK$. This makes sense because normally you only lock 
a record \«*ien you intend to update it. 



FINDS 

FIND$ locates and reads a MIDAS data entry by either primary or 
secondary key. Searches can be done on partial primary or secondary 
key values. The full key value as stored in the index subfile being 
searched, can be returned by FIND$ at the user's request. If a given 
secondary index contains secondary data, FIND$ can be told to return 
that instead of the data record. 



FIND$ Calling Sequence 

The calling sequence of FIND$ is: 

CALL FIND$ (funit, buffer, key, array, flags, altrtn, index, 
file-no, bufsiz, keysiz) 

The arguments v*iich have special meanings in this call are shown in 
Table 6-6. Flag values for FIND$ are listed in l^ble 6-7. 

Specifying Which Index to Use 

The index argument indicates v*iich access mode is being used on this 
call to FIND$. It also spells out v*iich index is to be used in a 
keyed-index file. Settings are: 

Index Values Meaning 

-1 Direct access — locate entries 

by record number 

Use primary index as search key 

1-17 Use indicated secondary 
index as basis of search 

See FIND$ and Direct Access for information on reading direct access 
files. 
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file-iK) Set this to 0: obsolete. 
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Table 6-6. FIND$ Arguments 



Argument 
funit 
buffer 

key 



array 

flags 

altrtn 
index 



buf si z 



Meaning 

File unit number on v*iich the MIDAS file is opened. 

Buffer in vJiich data entry, primary key values, or 
secondary data are returned as a result of call to 
FIND$. 

User supplies full or partial primary or secondary 
key value to use on this call. In direct access, key 
is not supplied unless FL$UKY is set in flags ; see 
below. 

The communications array — returned after each call 
with a completion or error code. In direct access, 
the user must supply the entry size and record number 
in words 2-4 of this array. 

See Table 6-7 for flags that can be used on calls to 
FIND$. 

Statement number in program of alternate return. 

Set to if primary index access. Set to 1-17 if 
secondary index access. Set to -1 for direct access. 

Length of buffer ; set to if complete data entry 
and primary key (if FL$KEY set on) are to be 
returned; otherwise specify number of wards you want 
returned from data subfile entry. 



keysiz 



Size of key ; set to if full key, otherwise set 
number of bits, bytes or wards in key . 



to 



- 31 



October 1980 



SECTION 6 



im4558 



Table 6-7. Flags for FINDS 



Flag 
FL$BIT 

FL$FST 

FL$KEY 

FL$NXT 



FL$PLW 



FL$PRE 



Meaning 

When set on, length of key is specified in keysiz in 
bits, if the key is defined as a bit string, or in 
bytes, if the key is an ASCII string. V*ien set off, 
keysi z is assumed to be in words. 

Tells FIND$ to 4to position to first entry in specified 
index subfile. If set off, FIND$ positions to first 
index entry that matches the user-supplied key, unless 
another flag setting overrules this. 

When set on, tells FIND$ to return the full value of the 
primary key for this record in buffer , beginning in 

will 



buffer (1). The returned data record 
iirmediately follow the primary key in buffer. 



then 



When set on, tells FIND$ to position to next index entry 
v*iich is greater than current or user-supplied entry. 
When set off, positions to index entry that matches 
current or user-supplied entry; may be overruled by 
flag setting with higher precedence (FL$FST) . Ihis flag 
setting is useful in partial key searches. 

If set on, tells FIND$ to fetch the next entry in the 
current index, vAiether greater than or equal to ("not 
less than," for CCBOL persons) the current or 
user-supplied entry. This is useful in partial key 
searches. When set off, positions to next entry in 
index only if it matches the current or user-supplied 
key value. (This can be overruled by other flag 
settings like FL$FST and FL$NXT.) 

When set on, tells FIND$ to position to index entry 
iirmediately prior to the current index entry. When set 
off, positions to index entry that matches the 
user-supplied key value, unless overruled by a flag 
setting with higher precedence. 
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FL$RET Tells MIDAS to return entire array after this call to 
FIND$. If set off, only the first ward of array , the 
completion code, is returned. 



FL$SEC When set on, returns secondary data from secondary index 
being searched instead of returning the data record. 
Secondary data is returned in buffer . Not applicable in 
direct access or primary index access, that is, if index 
is or -1. 

FL$UKY When set on, returns, in key , the full primary or 
secondary index value that corresponds to the 
user-supplied key value used in this call. 

FL$USE In keyed-index access, vrfien set on, tells MIEAS to use 

contents of array as returned by previous call. In 

direct access, the setting does not matter because the 
array is used anyway. 
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Specifying Key Values 

If index is 0, t±ie user must supply a primary key value in the key 
argument. Similarly, if a secondary index is indicated, a value from 
that index must be specified in key so FIND$ can use it in the 
retrieval. If the full key value is specified in key , the keysi z 
argunent can be set to 0. 

FIND$ Example 

Ihe following program reads records from the CUSTCMER file defined in 
Section 2. A variety of searches can be done with this program, 
including searches using full or partial primary or secondary key 
values. It also allows the user to retrieve the data subfile record 
referenced by the first entry in any specified index subfile, using the 
FL$FST flag. The program could easily be modified to find the previous 
or next index entry relative to the current entry by using the FL$PRE 
or FL$NXT flags. It is meant only as a general example of how to set 
up calls to FIND$, and is certainly not exhaustive. 

C READ EROGRAM FO^ CUSTOMER FILE 

C 

C THIS PROGRAM USES FIND$ TO LOCATE A RECORD BY ANY KEY 

C IT ALSO SHOWS HOW TO USE FL$FST TO RETURN FIRST ENTOY IN 

C ANY INDEX 

C 

$INSERT SYSCOM>KEYS.F 

$INSERT SYSCOM>PARM.K 

C EECLARATIOIS 

C Garden variety call parameters 

INTEGER*2 ARRAY(14) , INDEX, FUNIT,BUFFER( 35) , STATUS , FLAGS 

INTEGER*2 KEY(13) ,BUFSIZ,KEYSIZ,CODE 
C KEY IS MAX OF 13 WCMDS (SEC KEY01) 
C 

INTEGER* 2 ANSWER /* YES CB. NO 

CALL OPENM$ (K$READ+K$GETU, 'CUSTOMER' , 8, FUNIT, STATUS) 

IF (STATUS .NE. 0) GO TO 100 
01 CALL TNOUA ( ' SEARCH Otl PRIMARY? (Y or N) ' , 27) 

READ (1,3333) ANSWER 

IF(ANSWER .EQ. 'N') GO TO 05 
C ELSE IT'S A PRIMARY SEARCH 

INDEX = 

GO TO 10 
05 CALL TNOUAC ENTER SEARCH INDEX: ',20) /* SEC. INDEX NO. 

READ (1, 2222) INrs:X 
C GO C»I AND GET KEY VALUE 
10 CALL TNOUA ('USE YOUR KEY VALUE? (Y OR N) ' ,28) 

READd, 3333) ANSWER 

IF(ANSWER .EQ. 'Y') GO TO 15 
C ELSE USE FLSFST FLAG TO GET FIRST INDEX ENTRY 

FLAGS = FL$FST + FL$RET 

GO TO 45 
15 CALL TNOUA ('ENTER KEY VALUE: ', 18) 
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READ {1,1111) KEY 
20 CALL TNOUAC PARTIAL KEY? (Y OR N) ' ,21) 

READ (1,3333) ANSWER 

IF(ANSWER .EQ. 'Y') GO TO 30 
C ELSE ASSUME FULL KEY 

KEYSIZ =0 /* FULL KEY 

25 CALL TOOUAC RETURN ALL DATA? (Y or N) ' , 25) 

READd, 3333) ANSWER 

IF (ANSWER .NE. 'Y') GO TO 35 
C OTHERWISE, SET BUFSIZ TO 

BUFSIZ = 

GO TO 40 
30 CALL TNOUAC ENTER KEYSIZE IN WCM)S: ', 24) 

READd, 2222) KEYSIZ 

GO TO 25 
35 CALL TNOUAC ENTER DATA SIZE: ', 17) 

READd, 2222) BUFSIZ 

CONTINUE 
C MAKE CALL TO FIND$ 
40 FLAGS = FL$RET 
45 CALL FIND$(FUNIT, BUFFER, KEY, ARRAY, FLAGS, $200, INDEX, 0, 

+ BUFSIZ, KEYSIZ) 
C 

C DISPLAY WHAT'S IN BUFFER NOW 
50 CALL TNOUAC RECCED READ IS: ',16) 

CALL TNOU (BUFFER, 70) 
C Ask if want to go on 
60 CALL TNOUAC DO YOU WANT TO CONTINUE? (Y or N) ' , 33) 

READd, 3333) ANSWER 

IF (ANSWER ,EQ, 'N') GO TO 444 
C ELSE GO BACK TO TOP 

GO TO 01 



c 


FORMAT STATEWENTS HERE 




1111 


FORMAT {26A2) 


/* KEY ^-ALUE 


2222 


FORMAT (12) 


/* INDEX#, KEYSIZ, BUFSIZ 


3333 

C 

C 


FORMAT (A2) 


/* ANa^ER 


Error handlers next 




100 


CALL TNOUAC ERROR Oti OPEN: STATUS IS: 
CALL TODEC( STATUS) 
GO TO 444 


',24) 


200 


CALL TNOU ('ERROR m FIND: ',15) 

CALL TOOUAC INDEX IS: ',10) 

CAr.r, TODEC (INDEX) 

CALL TONL 

CALL TNOUAC ARRAY (1) IS: ',13) 

CALL TODEC ( ARRAY (1)) 

CAr.T, T(»JL 

GO TO 60 




444 


CALL CLOSM$(FUNIT, STATUS) 




555 


CALL EXIT 
END 
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Primary Key Search ; Ihe first example shows the use of a primary key 
to find a MIDAS file entry: 

SEARCH ON PRIMARY? (Y or N)Y 

USE YOUR KEY VALUE? (Y CR N) Y 

ENTER KEY VALUE: 4056S 

PARTIAL KEY? (Y OR N)N 

RETURN ALL DATA? (Y or N) Y 

RECCTID READ IS: 4056S EASTERN GRAPHICS NECN OLD SAYBROOK 

Secondary Key Search : This sample excerpt shows a search conducted on 
a secondary key value. 

SEARCH Oti PRIMARY? (Y or N)N 

ENTER SEARCH INMIX: 2 

USE YOUR KEY VALUE? (Y OR N) Y 

ENTER KEY VALUE: NWCR 

PARTIAL KEY? (Y OR N)N 

RETURN ALL DATA? (Y or N) Y 

mCORD READ IS: 2194G SPECTROGRAPHICS NWCH PORTLAND 

Using FL$FST : The FL$FST flag causes MIDAS to position to the first 
entry in tEe index specified and to return the associated data record. 
No key value need be supplied v^en FL$FST is used in a call to FIND$. 

SEARCH ON PRIMARY? (Y or N) Y 

USE YOUR KEY VALUE? (Y CM N)N 

RECCM) READ IS: 0816S MORROW PAPER MILLS NENH MCNAENOCK 

DO YOU WANT TO COOTINUE? (Y or N)y 

SEARCH m PRIMARY? (Y or N)N 

ENTER SEARCH INDEX: 1 

USE YOUR KEY VALUE? (Y OR N)N 

RECORD READ IS: 4056S EASTERN GRAPHICS NECN OLD SAYBROOK 

E^rtial Key Values : Full or partial keys may be used in both primary 
and secondary key searches. Partial key values must be prefixes of the 
full key value — that is, they must be taken from the beginning of the 
key value, not from the middle or the end. For example, if the key is 
"Massachusetts", legal partial values vrould be: "Mass", "Ma", 
Massach", "M" and so forth. During a partial key search, FIND$ 
returns the first data entry that has a key value beginning with the 
indicated partial value. 



n 



lb specify a partial key value, supply, in keysiz , the exact length of 
the value in key . If the key is a bit string or an ASCII string, its 
length should be specified in bits or bytes, as appropriate, and the 
FL$BIT flag should be set on. If FL$BIT is set off, the key size is 
assumed to be in words. 
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Here is an example of a partial key search using the READ program 
listed earlier: 



SEARCH Oti PRIMARY? (Y or N)N 

ENTER SEARCH INDEX: _1 

USE YOUR KEY VALUE? (Y OR N) Y 

ENTER KEY VALUE: EAST 

PARTIAL KEY? (Y OR N) Y 

ENTER KEYSIZE IN WORDS: 2 

RETURN ALL DATA? (Y or N) Y 

RECOffi READ IS: 4056S EASTERN GRAPHICS NECN OLD SAYBROOK 

If keys are not being stored in the record, set FL$KEY on in flags when 
doing partial key searches if you want the full key value to be 
returned . 



Retrieval Options 

FIND$ permits the retrieval of the following itons from a MIDAS file: 

• A data subfile entry (full or partial) — set bufsiz to to 
return all information. "lb return a partial entry, specify in 

• The primary key value associated with the record being sought — 
set FL$KEY on. This should be used v^en keys aren't stored in 
the data record, or vAien entries were added with FL$KEY set on 
during calls to ADD1$. Primary key value is returned in buffer . 
Set bufsiz to include both primary key and data record. 

9 Ihe secondary data stored with the secondary key value on v*iich 
the search is being conducted: secondary data is returned in 
buffer in place of data record, bufsiz can be set to to 
return all secomdary data, or to the number of vrords you want 
returned. Use FL$SEC in the call: index must be a value from 1 
- 17. 

• A full primary or secondary key value v^en searching on partial 
keys — set FL$UKY on: full key value is returned in key. 

All information returned by FIND$ is placed in buffer (except v*ien 
FL$UKY is used). Therefore, bufsiz must be specified accordingly 
during each call. 



- 37 October 1980 



SECTION 6 IDR4558 



V^hen to Use FL$KEY ; Ihe only cases in vi*iich it is necessary to set 
FL$KEY on (to return full primary key value) are: vrtien you aren't 
storing keys in the data record, or when FL$KEY was set on during calls 
to ADD1$. In these cases, setting FL$KEY in a FINDS is the only way 
you can find out v*iat the primary key value is for a given record. 

When to Use FL$UKY ; The FL$UKY flag is useful v*ien doing record access 
by partial key. It returns the complete value of the key v*iich MIDAS 
used to conduct the search. If keys are being stored in the record, 
this is good way of checking that the index entries correspond to the 
key values in the data record. In addition, these flags come in handy 
v*ien doing retrievals on duplicate keys as they can help identify v*iich 
record you're actually looking at. 



FIND$ and the Array 

During access to keyed-index MIDAS files, the user doesn't have to 
worry about the settings for the array argument in calls to FIND$. 
Vford 1 always returns a completion code to the user following a call to 
FINDS. If the value of array(l) is 0, the call was successful. If 1, 
the key value used in the call may occur more than once in the file. 
If array (1) has a value other than or 1, an error has occurred. 
Consult Appendix A to determine the nature of the problem. 

The entire array is returned to the user vAien the FLSRET flag is set in 
the call to FINDS. It can subsequently be used in calls to other 
routines like AmiS, NEXTS, DELETS and LOCKS. 



FINDS and Direct Access 

Direct access files can be accessed by any key or by entry number. "lb 
access a direct access file by primary or secondary use the keyed-index 
access method we've been talking about up to this point. Set index to 
the appropriate index subfile (key) number and set key and keysiz as 
described above. In other words, the direct access file is treated 
just like a keyed-index file. However, to access a direct access file 
by entry number (record number) , index must have a value of -1, and 
both key and keysiz should be set to 0. In some direct access files, 
the record entry number and the primary key may be the same, as in 
CCBOL RELATIVE files. 

Accessing a direct access file by entry number involves a search 
algorithm that calculates the p^iysical location of the record in the 
file, given the entry number and the data subfile record size, lb use 
the entry number method, supply a floating-point data entry number in 
array and the full data subfile entry size in bufsiz, in words. 
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Argument Settings : The index argument must be set to -1 in regardless 
of the search method used. If searching by primary key, key must 

must always be 0, indicating a full key value. In the entry nunber 
access method, the array argument must be set to the entry number to be 
used on this call. See Table 6-2, Direct Access Array Format , earlier 
in this section. It doesn't matter v^ether or not you set FL$USE 
because the array is always used by MIDAS in this type of call. 



NEXT$ 

NEXT$ is a powerful subroutine that allows a variety of operations to 
be performed on a keyed-index MIDAS file. NEXT$ can be used to: 

1. Itetrieve file records sequentially according to primary or 
secondary key order 

2. Retrieve all file records with a primary or secondary key value 
greater than some given key value 

3. Retrieve all records with the same partial key value 

4. Retrieve all records with duplicate index entries for a 
specified secondary key value 

5. Retrieve all records v\*K»se key values precede a certain key 
value in a given index subfile 

6. Retrieve a particular record using a full or partial primary or 
secondary key value (keyed retrieval) 

Special flag settings are required to perform these retrievals: see 
Table 5-9. 



Note 

NEXT$ cannot be used on direct access files. Therefore, index 
can never have a value of -1 in a call to NEXT$. Remember also 
that FL$RET must always be specified in calls to NEXT$, or a 
MIDAS error 30 will occur. 



NEXT$ Calling Sequence 

The calling sequence for NEXT$ is: 

CALL NEXT$ (funit, buffer, key, array, flags, altrtn, index, 
file-no, bufsiz, keysiz) 

Meanings for NEXT$ arguments are shown in "I^ble 6-8; flags settings 
for NEXT$ are described in Table 6-9. 
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Table 6-8. NEXT$ Argunents 



Argument 
funit 
buffer 



key 

array 
flags 

altrtn 

index 



file-no 



bufsiz 



keysiz 



Meaning 

Ihe file unit on v*iich the MIDAS file is opened. 

Buffer into vAiich retrieved data record or secondary 
data value is read. If FL$KEy is set, buffer will 
include key value plus data record. If FL$SEC is 
set, secondary data is returned instead of data 
record. See Table 6-9. 

Value of key to be used in search: can be full or 
partial, as specified in keysiz . 

MIDAS ccMtmunications array. 

Ebr flag options to be used in this call, see Tcible 
6-9. 



Statement number of alternate return to be 
event of program error. 



taken in 



Indicates index to be used: if set to 0, primary 
index is used; if greater than 0, secondary index 
subfile is used. Direct access is illegal ( index 
cannot be -1) . 

Set to (obsolete) . 

Length of data to be returned: if set to 0, full 
data subfile entry is returned. If FL$KEY is set on, 
the full key value is returned with the data. If 
FL$SEC is set on, secondary data is returned instead 
of the data subfile entry. Be sure to make the value 
of bufsiz large enough to accommodate everything that 
must be returned in buffer . 

Length of user-supplied key on this call. If set to 
0, full key value is used; if greater than 0, 
partial key is specified in either bits or bytes (if 
FL$BIT is set on) or in words (FL$BIT set off) . 
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Table 6-9. Flags for NEXr$ 



Flag Meaning 

FL$BIT V*ien set on, keysiz is specified in bits or bytes; v*ien 
set off, keysiz is in vords. 

FL$FST When set on, tells NE)Cr$ to return the record referenced 
by the first entry in the specified index. 

FL$NXT When set on, positions to next index entry greater than 
key . 

FL$PLW When set on, positions to next index entry greater than 
or equal to key . 

FL$PRE When set on, positions to index entry previous to 
current entry or user-supplied key . 

FL$RET Tells MIDAS to return contents of array after this 
call — this flag must be set on in all calls to NEXT$, 
othervdse an error 30 will occur. 



FL$SEC When set on, returns secondary data in buffer instead of 
data recoru; only used when index is > 1. If not set, 
secondary data is not returned]! "" 

FL$UKY When set on, key field used on this call is updated by 
MIDAS with full key value stored in the index, 

FL$USE When set on, MIDAS uses current contents of array ; 
array must be left over from a previous call to FIND$ or 
NEXT$. 



6-41 



October 1980 



SECTICN 6 im4558 



Buffer Size Specifications 

Data retrieved on a call to NEXT$ is returned in buffer . The amount to 
be read back is determined by the buf si z argument^ IE the entire data 
subfile entry is to be returned, set buf si z to 0. Similarly, when 
retrieving secondary data (when index is set to a value greater than 
and FL$SEC is set), set buf si z to 0. Otherwise, set this argument to 
the number of words you want returned from the index or data subfile. 
If FL$KEY is set in this call, the buffer size specified here is 
assumed to include the full primary key value. Make sure buf si z 
specifies a large enough buffer to include the full primary key (as 
well as the data record) when FL$KEY is used. 



Array Settings 

"Ihe only word of the array likely to be of any concern to the user on 
calls to NEXT$ is word 1 v*iich returns a completion code after the 
call, ^ain, the possible settings for array (1) are; 

Code Meaning 

Successful retrieval 

1 Successful retrieval, but 
duplicates may exist for 
this key value 

anything Something is wrong: 
else see Appendix A 



Sequential Record Retrieval 

To retrieve records sequentially from some point in a primary or 
secondary index (other than the beginning) , use FIND$ to locate the 
initial key value. Once the starting point is found, repeated calls 
should then be made to NEXT$ to return the data subfile records based 
on the order of entries in the primary or in a secondary index. In 
combination, FIND$ and NEXT$ calls effectively enable a "greater than 
or equal to" search: first you find a particular value, then you find 
all the values that are greater than or equal to it. Ihe key values 
are returned according to the collating sequence by v«*iich they were 
entered in the index subfile. 
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lb start this type of retrieval, set the FL$RET flag in the call to 
FINDS so the array can be used in the NEXT$ loop. Ihereafter, set the 
FL$RET and FL$USE flags in each call to NEXT$ so' the array can' be used 
in that call and returned for use on the next call. (The FL$USE flag 
tells NEXT$ to use the array as returned by the previous call.) 

From the Ibp ; Td retrieve file records sequentially, beginning with 
the first index entry in a given subfile, make a call to NEXT$ with 
FL$FST set on in flags. When set on, the FL$FST flag tells NEXT$ to 
return the record pointed to by the first index entry in the specified 
index subfile. Ihe index to be used in the retrieval is specified in 
the index argument of the call. Ihe FL$RET flag should also be set on 
in this call. After the initial call is made, the FL$FST flag is set 
off and the FL$PLW and FL$USE flags are set on in the subsequent call . 
This tells l«;XT$ to get the next entry in the index regardless of 
v^iether it matches the one just retrieved or not. 



NEXTS Example 

The program listed here accomplishes two types of retrievals: it 
retrieves all the entries in the CUSTOMER file, in order by primary 
index entry, and it finds all the duplicates of a particular secondary 
key value. 

C "NEXT" PROGRAM FOR CUSTOMER FILE 

C 

C THIS PROGRAM RETRIEVES DUPLICATES FROM A SECCMDARY INDEX 

$ INSERT SYSCOM>KEYS.F 

$ INSERT SYSCOM>PARM.K 

C DECLARATIONS 

C Garden variety call parameters 

INTEGER*2 ARRAY(14) , INDEX, FUNIT,BUFFER( 35) , STATUS, FLAGS 

INTEGER*2 KEY(13) ,BUFSIZ,KEYSIZ,CODE 
C KEY IS MAX OF 13 WORDS (SECONDARY KEY 01) 

INTEGER* 2 J /* TRACKS # OF DUPS 

C 
10 CALL OPENM$ (K$READfK$GETU, ' CUSTOMER' , 8 , FUNIT, STATUS) 

IF (STATUS .NE. 0) GO TO 200 /* ERROR HANDLER 

C GET ALL ENTRIES OUT OF PRIMARY INDEX 
20 INDEX = 

KEYSIZ = 

BUFSIZ = 
C 

C USE FL$FST FLAG TO GET FIRST ENTRY 
30 FLAGS = FL$RET + FL$FST 

CALL NEXT$ (FUNIT, BUFFER,KEY,ARRAY,FLAGS, $300, INDEX, 0, 
+ BUFSIZ, KEYSIZ) 
C 
C DISPLAY WHAT'S IN BUFFER NOW 

CALL TOtiL /* BLANK LINE 

40 CALL TNOUAC RECORD READ IS: ',16) 

CALL TNOU (BUFFER, 70) 
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CALL TONL 

C 

45 CALL TNOUC RETRIEVE RECORDS IN ORDER BY KEY', 32) 

C 

C RETRIEVES RECORDS IN INDEX ENTRY ORDER 

C 

C USING FL$NXT FLAG WHICH TELLS MIDAS TO 

C GET NEXT ENTRY GREATER THAN THE CURRENT 

C INDEX ENTRY. 

C DCN'T F0R3ET TO RETURN ARRAY!!! 

C 

50 FLAGS = FL$USE + FL$NXT + FL$RET 

CALL NEXT$(FUNIT,BUFFER,KEY,ARRAY,FLAGS,$60,INDEX,0, 
+ BUFSIZ,KEYSIZ) 

CALL TOtiL /* BLANK LINE 

C 

CALL TOOU('NEXT RECORD IS: ',16) 

CALL TNOU (BUFFER, 70) 
55 GO TO 50 /* REPEAT UNTIL DONE 

C 
60 CALL TOOUCEND OF ENTRIES IN INDEX 0',25) /* END OF INDEX 

CONTINUE 
C 

CALL TOSIL 
70 CALL TNOU {'FIND DUPLICATES IN SECONDARY INDEX 02', 37) 

INDEX = 2 

CALL TNOUA('KEY VALUE TO USE?', 17) 

READ( 1,1111) KEY 
C 
75 FLAGS = FL$RET /* FIND FIRST ENTRY 

CALL NEXT$(FUNIT,BUFFER,KEY,ARRAY,FLAGS,$300,INDEX,0, 
+ BUFSIZ,KEYSIZ) 
C PRINT OUT RECORD 

CALL TOIL 

CALL TNOU ('RECORD READ IS: ',16) 

CALL TNOUJBUFFER, 70) 
C 

C READ ALL DUPLICATES 
C J KEEPS TRACK OF # OF DUPLICATES FOUND 

j=0 /* INITIALIZE COUNTER 

80 FLAGS = FL$USE + FL$RET 

CALL NEXT$ (FUNIT, BUFFER,KEY,ARRAY, FLAGS, $100, INDEX, 0, 
+ BUFSIZ,KEYSIZ) 
C PRINT OUT RECORD 

CALL TOIL /* BLANK LINE 

CALL TNOU ('NEXT DUPLICATE IS: ',19) 

CALL TNOU (BUFFER, 70) 

J=J+1 /* KEEPS TRACK OF # DUPS 

85 GO TO 80 
C 

C IF FALL THRU LOOP, CHECK VALUE OF J 

100 IF (J .EQ. 0) GO TO 150 /* NO DUPS FOUND AT ALL 

C ELSE WE RAN OUT OF DUPLICATES 
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CALL TNOUCNO MORE DUPLICATES' ,18) 
GO TO 444 



/* CLOSE FILE 



150 CALL TNOUCNO DUPLICATES FOUND FCR THIS KEY', 32) 

GO TO 444 /* CLOSE FILE 

C 

1111 F(M1AT(26A2) /* FCMIAT FOR KEY ARG 

C ERROR HANDLERS 
C 
200 CALL TNOUAC ERROR (M OPEN. STATUS IS: ',24) 

CALL TODEC( STATUS) 

CALL TOIL 

GO TO 444 

CALL TNOUC ERROR CN CALL TO NEXT: ' ,23) 

IF (ARRAY (1) .EQ. 7) CALL TNOU(' RECORD NOT FOUND', 16) 

CLOSE FILE 

CALL CL09M[$(FUNIT, STATUS) 

CALL EXIT 

END 



C 

300 

C 

444 

555 



Sequential Retrieval Example: This sample session excerpt shows the 
records retrieved by the first part of the above program: 



OK, SBG #NEXT 

RECORD READ IS: 0816S MCM^OW PAPER MILLS 

RETRIEVE RECORDS IN ORDER BY KEY 



NENH MCWAI»JOCK 



NEXT RECORD IS: 
1002P FLORA PORTRAITS 

NEXT RECORD IS: 
2194G SPECTROGRAPH ICS 

NEXT RECORD IS: 
2334P PERFECT PRINTS 

NEXT RECORD IS: 

4056S EASTERN GRAPHICS 

NEXT RECCMD IS: 
9402A ARTISTRY UNLTD. 

NEXT RECORD IS: 

94 IIP STUDIO WEST 

END OF ENTRIES IN INDEX 



NENY CROTC»I-ON-HUDSCW 



NWOR PORTLAND 



WRCA SANTA BARBARA 



NECN OLD SAYBROOK 



WRCA MOvlTEREY 



WRCA PALO ALTO 



45 
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Retrieving Duplicates 

NEXT$ can retrieve duplicate secondary key values and primary key 
values that begin with identical prefixes. Only prefix values can be 
used in partial key searches, that is, the key value supplied must be 
extracted from the initial portion of the full key value. For example, 
if the full key is "Brookline", legal prefixes wauld include "Brook", 
"Bro", "Br", and so forth. 

Tb perform a duplicate key search, use a FIND$ (with FL$RET set) , or 
use NEXT$ without FL$USE, to retrieve the first entry with the desired 
full or partial key value. The rest of the values that match this one 
can be found by calling NEXT$ with FL$USE set on. (FL$NXT and FL$PLN 
are set off.) The FL$RET flag should be set on for all calls to NEXT$ 
v*ien doing this type of retrieval. 

Duplicate Example ; The NEXT program listed earlier allows you to 
retrieve records with duplicates of any secondary key value desired. 
Ebr example, here is some output from a sample run of the NEXT program, 
using the value "WRCA" for secondary index 02: 



FIND DUPLICATES IN SECCMIARY INDEX 02 
KEY VALUE TO USE7 WRCA 

RECCM) READ IS: 

941 IP STUDIO WEST WRCA PALO ALTO 

NEXT DUPLICATE IS: 

9402A ARTISTRY UNLTD. WRCA MONTEREY 

NEXT DUPLICATE IS: 

2334P PERFECT PRINTS WRCA SANTA BARBARA 

NO MCBE DUPLICATES 



Retrieving E>revious Records 

To find all the records v*iose index values are less than or equal to a 
certain key value, set the the FL$PRE flag on. First, you must have a 
key value to start with. Establish this with a call to FIND$ or NEXT$ 
with the FL$USE flag set off. Then call NEXT$ with FL$PRE, FL$USE and 
FL$RET set on. The search should fail v*ien the first index entry in 
the index subfile is reached. 
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On page 6-47, the line describing bufsiz should read; 

bufsiz Size of buffer in bytes, 
(The manual currently says "words" instead of "tytes".) 
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GnATA$ 

The GDAT.^x$ routine retrieves records directly from the data subfile in 
the physical order stored, that is, the order in v*iich they appear in 
the data subfile. This order does not necessarily correspond to any 
key order, unless the records were added in order by primary key, or 
unless the file has just been MPACKed. 

In order to use GnATA$, the FL$FST flag must be set on in the first 
call; the FL$NXT flag must be set on in subsequent calls. 



Caution 

Successive calls to GDATA$ with FL$NXT set should not be mixed 
with calls to other MIDAS file access routines because GDATA$ 
does not use the MIDAS array to keep track of current index 
position. 



GDATA$ Calling Sequence 

GDATA$ does not use the general calling sequence used by the other data 
access subroutines. Instead, it has its own: 

v.<m.iij uiJninp ^'^-''''f i-±a^s> t uuLj-cl , Dui.s>i^i i^Louu^sj 

These arguments and their meanings are: 

Arqument Meaninq 

unit PRIMCe file unit on v*iich MIDAS file is opened. 

flags Set FL$FST to retrieve first data record: this must 
be used for initial call. Set FL$NXT flag on to 
retrieve next sequential record in data subfile. 

buffer Buffer in which data is returned. 

bufsiz Size of buffer in JMMalflN hyJl:^, 

status Error status code: may be one of the following: 

No error 
>0 Systan error code 
-1 Bad flags value supplied 
-2 Bad index descriptor 
-3 Invalid record position 
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The data buffer, buffer , contains the retrieved data record upon 
returning from a GDATA$ call. 



UPDATING A RECCED 

Record updates are performed by jointly using the LOCK$ and UPDAT$ 
routines. LOCK$ secures a record for update, preventing other users 
from locking or updating it. It does not, however, prevent other users 
from deleting a locked record, lb update a record, it must first be 
locked with LOCKS and then updated with UPDAT$ inmediately thereafter. 

CALL9 TO lOCKi, A/Vfi UPPAT^ 

LOCK$ 

LOCK$ works on both keyed-index and direct access MIDAS files. It 
works essentially like FIND$ except that it also locks the record it 
retrieves. Like FIND$, LOCK$ returns the located data record in 
buffer. LOCK$ cannot lock an already locked record, and will return an 
error upon an attempt to do so. When LOCK$ is successful, the record 
will remain locked until UPDAT$ is called to update that record. A 
successful LOCK$ must always be followed by a call to UPDAT$ (otherwise 
the record can't be unlocked). 

LOCK$ Calling Sequence 

Ihe LOCK$ calling sequence is: 

CALL LOCK$ (funit, buffer, key, array, flags, altrtn, index, 
file-^^o, bufsiz, keysiz) 

An explanation of these arguments appears in Table 6-10. Pertinent 
flags values are addressed in Table 6-11. 
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On page 6-48, add the following sentence to the end of the paragraph 
entiUed UHJATING A REOORD: 

MHas calls that process other files can be wade between calls to 
LOOC? and UH)AT$. 



On page 



6-49, the argument listed as key value *ould be sinply tey. 
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Table 6-10. LOCK$ Argiments 

Meaning 

Ihe file unit on v*iich the MIDAS file is open. 

Ihe buffer into viiich the data record to be locked is 
read. 

Full primary or secondary key value v^ich 
identifies the record to be locked; not necessary if 
record already found on a call to FIND$ or NEXT$. 

Ebr keyed-index access, set to or 1 on input. Ebr 
direct access, array must include the user-supplied 
record entry number and size to identify the record to 
be locked. See IJXK$ and Direct A::cess . 

Ebr flags that can be used with LOCK$, see Table 6-11. 

An alternate return to be taken in the event of an 
error. 

In keyed-index, set to for primary index access, 
1-17 for secondary index access, and to -1 for direct 
access . 

Set to 0. 

Length of data to be read from file: it's a good idea 
to set it at (to return the v*iole record). However, 
if FL$KEY is set on, make sure buf si z is large enough 
to include complete primary key. 

keysiz Ignored by LOCK$: full key, is assumed if supplied. 



Argunent 
funit 
buffer 



key 



array 

flags 
altrtn 

index 

file-no 
buf si z 
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'teble 6-11. flags for LOCK$ 

Flag Meaning 

FL$KEY Set on to include full primary key value in buffer along 
with data record; use only if keys are not stored in the 
record . 

FL$RET Must be set on in each call to LOCK$ so that UPDAT$ can 
use the array returned by this call. If not set, an 
error 30 occurs. 

FL$USE Set on if record to be locked was already found by an 
immediately prior call to FIND$ or NEXT$; the array 
returned by the previous call is used on this call to 
LOCK$, and the user does not have to supply a value for 
key . 
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Specifying a Key 

In order to lock a record, it must be retrieved and trade current. "lb 
retrieve the record to be updated, a full key value must be supplied in 
key on a call to LOCK$, or a valid array must be supplied by a previous 
call anA FL$USE must be set on. The record to be updated can be 
positioned to and locked via the primary or secondary key. You may 
specify a value for keysiz if you want, but it will be ignored because 
a full key is always assumed if a value for key is supplied in the 
call. Partial key retrieval is possible only if you use FIND$ or NEXT$ 
first with FL$UKY and FL$RET set on in flags. A subsequent call can 
then be made to LOCKS with FL$USE set on. No key is required in this 
call to UX:k$ because the data record has already been located by the 
previous FIND$ or NEXT$ call. 



The Array in LOCK$ 

When the entry to be updated has already been found on a previous call 
to FINDS or NEXTS (with FL$RET set on) , FL$USE should be set on in 
flags on the call to LOCKS, array can be set to or 1 on the LOCKS 
call. When returned, as a completion code, the first word of the array 
may contain one of the following values: 

Value Meaning 

Successful retrieval 

1 Successful retrieval but there may be duplicates of 
this key value (secondaries only) 

7 Entry not found 

10 Ehtry found, but already locked 

Anything See Appendix A 
Else 



Note 

Ch all calls to LOCKS, FL$RET must be set on so that the 
irtmediately subsequent call to UPDATS can use the array 
returned by the LOCKS operation. 



LOCKS and Direct Access ; In direct access, the use of LOCKS is 
identical to its use on keyed-index access. "The only differences are 
that index must be set to -1, and that array must include the data 
entry number and size on any call that does not use an array returned 
by a prior call to FINDS. The array must be set up as follows: 
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Mbrd Number Setting 

1 If set to 1, tells MIDAS to use array contents. 
If set to -1, array contents are not used. 

2 Supply entry size (in wards) . This includes the key 
length (in words) plus secondary data length (in 
wards) plus 2 words. 

3-4 Supply the record entry number. This is a 
single-precision (REAL*4) floating-point record 
number. 

5-14 Set to (obsolete) . 

Records may be retrieved prior to locking by calling FIND$ with FL$RET 
set on; LOCK$ is then called with FL$USE set on. Ihere is no need to 
reset the array in this case. 



UPDATS 

A call to UPDAT$ must always be preceded by a call to LOCK$. Qieck the 
returned completion code in array(l) after the LOCK$ call to make sure 
that the record was successfully locked before doing a call to UPDAT$. 
Record updates can be done on both keyed-index and direct access MIDAS 
files. An update is a true rewrite of the record as returned in 
buffer . After the call, the record is unlocked. A call to UPDAT$ with 
FL$ULK set on simply unlocks the locked record without updating it. 



UPDAT$ Calling Sequence 

The calling sequence for UPDAT$ is: ^-y^ 



CALL UPDAT$ (funit, buffer, 'array, flags, altrtn, index, 
file-no, bufsiz, keysiz) 

Because key values are not supplied in updates, both the key and keysiz 
arguments should be set to in a call to UPDAT$. Index must match 
index specified on the prior call to LOCK$. the updated record is 
supplied in buffer. All the UPDAT$ arguments are described in "I^ble 
6-12. The flags that may be used on calls to UPDAT$ are described in 
Table 6-13. 

Uhlock Chly ; If an entry is to be unlocked only, (not updated) set 
FL$ULK on in flags , buffer does not have to be altered in this case. 

UPDAT$ and the Array ; Since a copy of the array as returned by LCX:k$ 
must be used in every call to UPDAT$, the FL$USE flag must be set on. 
array is effectively supplied by FL$USE being set on and should not be 
tampered with following a call to LOCK$. The completion code returned 
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On pages 6-52 and 6-58^, the key argument vas inadvertently 
onitted from the calling sequences, although it does apgeax in 
the argument eiqplanation lists on pages 6-53 and 6-59. Ihe key 
ar^Jnient should be inserted between the bu££er and array 
arguments in these Cedling sequences. 



On page 6-52, insert the k^ argument between the buffer and arr^ 
arguments in tiie UH]AT$ calling sequence. Bie calling sequence should 
now read: 

CALL UPDAT$ (fimit, buffer, key, array, flags, altrtn, index, 
file-no, bufsiz, keysize) 
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Table 6-12. UPnAT$ Arguments 

Arg'jnent Meaning 

funit File unit on v*iich MIDAS file is opened. 

buffer Buffer v*iich contains the updated last record. If 
FL$KEY was set in the previous call to LOCK$, the 
primary key should be included in buffer . If keys are 
being stored in the data record, make sure all keys 
are supplied. 

key Ignored: set to 0. 

array Supplied by previous call to LOCK$: should already be 
set to or 1. 

flags For flags options on update calls, see T^ble 6-13. 

altrtn Alternate return to be taken in event of error. 

index Set to if primary index was used in IjOCK$ call; set 
to 1-17 if secondary index was used in LOCK$ call. If 
direct access, set to -1. index setting for UPDAT$ 
must match its setting in previous call to LOCK$. 

file-no Set to 0. 

bufsiz Same as in call to LOCK$. (Ignored) 

keysiz Partial keys do not apply in updates. (Ignored) 
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Table 6-13. Flags for UPDAT$ 

Flag Meaning 

FL$KEY When set on, indicates that a full primary key is present 
in buffer . Used only v*ien keys are not being stored in 
the data records. 

FL$ULK When set on, tells UPDAT$ to unlock the record only: all 
other flags settings are ignored and the data record is 
not updated. 

FL$USE Must be set on so that the array returned by prior LOCK$ 
call is used on the UPDAT$ call. If not set on, an error 
30 occurs. 
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On page 6-54, add the following note to tiie bottcm of Table 6-13: 

FL^^ET Ignored by UIDAT$, Note that UIDAT$ always resets tiie 
flag in the array vihich indicates whether or not a record is 
locked. 



im4558 THE FORTRAN INTERFACE 



operation indicates v^iether or not the update was successful. If 
array (1) is returned as 0, the update was successful. If returned as 
11, the entry was not locked as expected and the operation failed. 
Other errors can occur as well, such as a concurrency error if the 
record was deleted by another user in between the LOCK$ and UPDAT$ 
calls. See Appendix A for a list of MIDAS error codes. 



Caution 

Neither primary nor secondary keys may be changed in a call to 
UPnAT$; this includes secondary data values. It's never 
permissible to change the value of a primary key anyway. Where 
keys are stored in the data record, changes to secondary key 
fields during a call to UPnAT$ will have no effect on the 
actual secondary index subfile entries that point to the record 
being updated. lb change a secondary index entry and/or 
secondary data, you must delete the entry from the index 
subfile, and then re-add it in the desired form. If keys are 
being stored in the data record, you should then update the 
data subfile record accordingly. 



UPDAT$ Example 

Ihe UPDATE program below shows the use of LOCK$ and UPDAT$ in updating 
a record in a MIDAS file. 

C UPDATE PRCX]RAM FOR CUSTOMER FILE 

C 

C THIS PROGRAM FINDS A RECCED ON ANY INDEX 

C THEN LOCKS AND UPDATES IT AT THE USER'S REQUEST 

C 

$ INSERT SYSCCM>KEY3.F 

$INSERT SYSC(>!>PARM.K 

C DECLARATIONS 

C Garden variety call parameters 

INTEGER*2 ARRAY(14) , INDEX, FUNIT, BUFFER (35) , STATUS, FLAGS 

INTEGER*2 KEY(13) ,BUFSIZ,KEYSIZ,CODE 
C KEY IS MAX OF 13 WORDS 

INTEGER*2 DATA(17) /* NON-KEY PART OF REC(»D 

C 

C 

C 



INTEGER* 2 ANSWER /* YES OR NO 

EQUIVALENCE ( BUFFER (19), DATA ( 1 ) ) 



CALL OPENM$ (K$READfK$GETU, ' CUSTOMER' , 8 , FUNIT, STATUS) 

IF (STATUS .NE. 0) GO TO 100 
C 
01 CALL TNOUA ('SE/tfiCH 0* PRIMARY? (Y or N) ' , 27) 

READ (1,3333) ANSWER 

IF(ANSWER .EQ, 'N') GO TO 05 
C ELSE IT'S A PRIMARY SEARCH 

INDEX = 
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GO TO 10 
05 CALL TNOUAC ENTER SEARCH INDEX: ',20) /* SEC. INDEX NO. 

READ (1,2222) INDEX 
C GO Oti AND GET KEY VALUE 
10 CALL TNOUAC USE YOUR KEY VALUE? (Y C» N) • ,28) 

READ (1,3333) ANSWER 

IF(ANSWER .EQ. 'Y') GO TO 15 
C ELSE USE FL$FST FLAG TO GET FIRST INDEX ENTRY 

FLAGS = FL$FST + FL$RET 

GO TO 25 
15 CALL TNOUAC ENTER KEY VALUE: ', 18) 

READ(1, 1111) KEY 

KEYSIZ =0 /* FULL KEY 

BUFSIZ = 
C MAKE CALL TO FIND$ 

20 FLAGS = FL$RET 
25 CALL FIND$(FUNIT,BUFFER,KEY,ARRAY,FLAGS,$200,INDEX,0, 

+ BUFSIZ, KEYSIZ) 
C ELSE PRINT OUT RECCED 

C DISPLAY WHAT'S IN BUFFER NOW 

30 CALL TNOUAC RECCED READ IS: ',16) 

CALL TNOU (BUFFER, 70) 
C 

C UPDATE RECCM) 
40 CALL TNOUAC UPDATE THIS RECCM)?', 19) 

READ (1,1111) ANSWER 

IF(ANSWER .EQ. 'N') GO TO 01 
C 
C ELSE LOCK AND UPDATE 

FLAGS = FL$USE + FL$RET 
C ALWAYS RETURN ARRAY (M CALL TO LOCK$ 
50 CALL LOCK$(FUNIT,BUFFER,KEY,ARRAY,FLAGS,$300,INra:X,0, 

+ BUFSIZ, KEYSIZ) 
C 

C IF NO ERROR, WE CAN UPDATE 
C CHANGE NON-KEY PORTIOl OF DATA RECORD 

CALL TOOUAC ENTER NEW DATA: ',15) 

READ (1,4444) DATA 
C 
C GO AHEAD AND UPDATE 

FLAGS = FL$USE 
59 CALL UPDAT$(FUNIT,BUFFER,KEY,ARRAY, FLAGS, $400, INDEX, 0, 

+ BUFSIZ, KEYSIZ) 
C 

C IF NO ERROR, ASK IF WANT TO CaOTINUE 

70 CALL TNOUAC DO YOU WANT TO CCKTINUE? (Y or N) ' , 33) 

READ (1,3333) ANSWER 

IF (ANSWER .EQ. 'N') GO TO 444 
C ELSE GO BACK TO TOP 

GO TO 01 
C 

C FORMAT STATEMENTS HERE 

1111 F0RMAT(26A2) /* KEY VALUE 

2222 FORMAT (I 2) /* INDEX#, KEYSIZ, BUFSIZ 
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3333 FORMAT (A2) /* ANSWER 

4444 FORMAT (34A2) /* DATA 

C 

C 

C Error handlers next 

100 CALL TNOUA( 'ERROR ON OPEN: STATUS IS: \2A) 

CALL TODEC (STATUS) 

GO TO 444 
200 CALL TNOUC ERROR OI FIND: ',15) 

GO TO 70 
300 CALL TNOUC ERROR C»I LOCK', 13) 

CALL TNOUA( 'MIDAS ERROR IS:', 15) 

CALL TODEC ( ARRAY (1)) 

GO TO 444 /* CLOSE FILE 

400 CALL TNOUCERRCR OJ UPDATE ',15) 

CALL TNOUA( 'MIDAS ERROR IS:', 15) 

CALL TODEC ( ARRAY (D) 
C CLOSE FILE 
C 

444 CALL CLOSM$(FUNIT, STATUS) 
555 CALL EXIT 

END 

This excerpt from a sample execution of the above program shows a 
record update involving only the non-key portion of the data subfile 
record : 

SEARCH CW PRIMARY? (Y or N) Y 

USE YOUR KEY VALUE? (Y OR N) Y 

ENTER KEY VALUE: 9402A 

RECORD READ IS: 9402A ARTISTRY UNLTD. WRCA MOITEREY 

UPDATE THIS RECORD?Y 

ENTER NEW DATA: CARMEL 

DO YOU WANT TO CONTINUE? (Y or N)N 

Now, use the READ program to see if the record was updated properly. 

OK, SEG #READ 

SEARCH CN PRIMARY? (Y or N) Y 

USE YOUR KEY VALUE? (Y CR N)Y 

ENTER KEY VALUE: 9402A 

PARTIAL KEY? (Y OR N)N}^ 

RETURN ALL DATA? (Y or N)Y 

RECORD READ IS: 940 2A ARTISTRY UNLTD. WRCA CARMEL 
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DELET$ 

DELET$ can remove either a data subfile entry (and its associated 
primary key) or a secondary index entry. When a primary index entry 
and record entry are deleted, the associated secondary index entries 
(if there are any) are not deleted. Instead, they are marked for 
deletion, and the space they occupy is not reclaimed until the entry is 
referenced in an interface subroutine call, or until the file is 
MPACKed (see Section 12) . 

DELET$ ignores the fact that a record may be locked and deletes it 
anyway. It is not necesary to precede DELET$ with a call to another 
subroutine like FIND$ or NEXT$ because DELET$ can position to as well 
as remove a record or an index subfile entry. Records can be deleted 
from both keyed-index and direct access files. 



DELET$ Calling Sequence 

The DELET$ calling sequence is the same one shared by all the other 
interface routines. Some arguments are ignored by MIDAS and can be 
supplied as in the call. 

CALL ra:LET$(funit, buffer, 'array, flags, altrtn, index, 
file-no, bufsiz, keysiz) 

The argunents for DELET$ are shown in Table 6-14. 



Locating the Record to Delete 

A record to be deleted may be located by either primary or secondary 
key value. Simply give DELET$ the full primary or secondary key value 
in key and set index appropriately. However, a FIND$, NEXT$ or LCCK$ 
operation may be used prior to a delete operation to establish the 
record to be deleted. In this case, the FL$RET flag should be set in 
this prior call so that DELET$ can use the returned array. Ihe call to 
EELET$ must then set FL$USE in flags. The key and keysiz arguments are 
ignored vA^en FL$USE is set on in the call. 



Deleting Duplicates 

When deleting duplicate key entries you must use NEXT$ to locate the 
particular record you want deleted. Neither DELET$ nor FIND$ will do 
the trick unless the record or index entry you want deleted happens to 
be the oldest of the duplicates in a particular subfile. The "oldest" 
duplicate is always the first one that physically appears in the index. 
Both DELET$ and FIND$ are unacceptable because they automatically 
position to the oldest duplicate value for that key in the file. 
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On pages 6-52 and 6-5ff, the key argument was inadvertently 
omitted from the calling sequences, alttiough it does appear in 
the argument ej^Jlanation lists on pages 6-53 and 6-59, a!he key 
argument should be inserted between the buffer and arr^ 
arguments in these calling sequences. 
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Table 6-14. DELETS Arguments and Flags 
Argument Meaning 

£u"it Ihe file unit on v*iich the MIDAS file is open. 

buffer Ignored . 



key 



Full primary or secondary key to be used in 
identifying the entry to be deleted. No need to 
supply a value for this if using the array from the 
previous call (assumes FL$USE is set) . 

Supply array (1) as or 1 in keyed-index access. In 
direct access, words 2, 3 and 4 must include entry 
number and data size. See DELET$ and Direct Access . 

The only applicable flag in this call is FL$USE v*ich 
should be set if a previous call to FIND$ or NEXT$ was 
made to locate entry to be deleted. All other 
settings for flags will be ignored. 

Alternate return to be taken if error on call. 

Indicates vAiether a data record (and primary index 
entry) or a secondary index entry should be deleted. 

If 0; deletes primary index entry and the data record 
it references. 

If 1-17; deletes secondary index entry from specified 
index . 

If -1- deletes primary index and data entry from a 
direct access file. 



file-no Set to 0: obsolete. 

bufsiz Ignored on this call: set to 0. 

keysiz Ignored on this call: set to 0. 



array 



flags 



altrtn 



index 
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Deleting Secondary Index Ehtries 

A secondary index entry may be removed without touching the data record 
it references, and without deleting the primary index entry associated 
with it. The entry to be deleted can be located by a call to DELET$ 
with FL$USE set off and index and key set to the index number and full 
key value to be used in the call. 

Alternatively, the secondary index entry to be deleted can be located 
with a call to FINDS or NEXr$ with FL$RET set in flags and with index 
set to the appropriate secondary index subfile number. The key value 
specified must be an entry within that index. A call to either FIND$ 
or NEXT$ is then followed by a call to KILETS with FL$USE set on and 
with the value for index unchanged, key can be set to since it is 
ignored v*ien FL$USE is set anyway. 



Removing a Record and All Ifeys 

Although a records' secondary key entries will eventually be deleted, 
either by referencing them through a MIDAS call or by MPACKing the 
file, it is sometimes desirable to remove all secondary key entries 
explicitly. Fbr example, in situations vAiere a large number of records 
have been deleted and their secondary key entries have not, if someone 
did a call to FIND$ with FL$NXT set, for example, it vould take quite a 
v*iile for MIDAS to step throtgh that secondary index looking for an 
index entry that points to an existing data record. Chances are that 
the secondary index subfile will contain many useless entries that 
point to nothing. One way to get around this is to delete all the 
secondary index entries before the actual data record is deleted. 

First, delete all the secondary index entries that reference this 
record, then delete the data record and its primary index entry. This 
process is greatly simplified if you store all the keys in the data 
record, because once you retrieve the data record, you can tell vAiat 
the keys are and you can delete the appropriate ones. If you don't 
make a habit of storing the keys in the data subfile record this could 
be a time-consiming process. In this case, you'd be better off 
deleting the record by primary key and then MPACKing the file to 
reclaim the secondary index and data subfile space. 



EELETS Example 

Although it is not necessary to do a FIND$ before a call to DELET$, the 
program shown here does, simply because it's a good idea to verify that 
a record should be deleted before the delete actually occurs. This is 
true mainly in an interactive application, so you certainly can 
dispense with the precautions if you wish. This program also deletes 
all the secondary index entries associated with the record before the 
data entry is removed. This guarantees that no space will be taken up 
in any of the secondary index subfiles by useless entries. 
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C DELETE HIOGRAM FOR CUSTCMER FILE 

C 

C THIS PROGRAM USES FIND$ TO LOCATE THE RECCM) TO BE 

C DELETE BY PRIMARY KEY AND PRINTS IT OUT. 

C IT MILETES ALL SECONDARY INDEX ENTRIES FIRST, THEN 

C PRIMARY INDEX AND LATA SUBFILE ENTOY ARE REMOVED. 

C 

$INSERT SYSCOM>KEYS.F 

$INSERT SYSCOM>PARM.K 

C DECLARATI(»JS 

C Garden variety call parameters 

INTBGER*2 ARRAY(14) ,INDEX,FUNIT,BUFFER(35) ,STATUS,FLAGS 

INTBGER*2 BUFSIZ,KEYSIZ,CODE 

INTBGER*2 PKEY(3) ,SKEY1(13) ,SKEY2(2) /* KEYS FOR FILE 

INTEGER* 2 ANSWER /* YES CR NO 

C 

C EQUIVALENCE KEYS TO PARTS OF BUFFER 
C 

EQUIVALENCE (PKEY(l) ,BUFFER(1) ) , 

* (SKEYl (1) ,BUFFER{4) ) , 

* (SKEY2(1),BUFFER(17)) 
C 

10 CALL OPENM$ (K$READf K$GETU, ' CUSTOMER' , 8 , FUNIT, STATUS) 

IF (STATUS .NE. 0) GO TO 100 
15 CALL TNOUAC ENTER PRIMARY KEY ThWE OF RECORD TO BE DELETED: ' ,48) 

READ (1, 1111) PKEY 
C SET OTHER ARGUMENTS APPROPRIATELY 
C 

INDEX = 

KEYSIZ =0 /* FULL KEY 

BUFSIZ = 
C MAKE CALL TO FIND$ 

FLAGS = FL$RET 

20 CALL FIND$(FUNIT,BUFFER,PKEY,ARRAY.FLAGS,S200.INDEX,0- 

+ BUFSIZ, KEYSIZ) 
C DISPLAY WHAT'S IN BUFFER NOW 
25 CALL TNOUAC RECCM) IS: ',11) 

CALL TNOU (BUFFER, 70) 
C 

CALL TNOUAC OKAY TO DELETE?: ',17) 

READ (1,2222) ANSWER 

IF (ANSWER .EQ. 'N') GO TO 15 
C ELSE DELETE 

C NCW DELETE EACH SECCNDARY INDEX BEFORE DELETING DATA RECORD 
C 

INDEX = 1 

ARRAY(l) =0 /* RESET WORD 1 OF ARRAY 

C OTHER ARGS REMAIN UNCHANGED EXCEPT FCR KEY VALUE 

30 CALL DELET$(FIJNIT,BUFFER,SKEY1,WIRAY,FLAGS,$300,INDEX,0, 

+ BUFSIZ, KEYSIZ) 
C 
C NOW DELETE INDEX ENTRY FRCM INDEX SUBFILE 02 

INDEX = 2 
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ARRAY(l) = 
40 CALL DELET$(FUNIT,BUFFER,SKEY2,ARRAY,FLAGS,$300,INDEX,0, 
+ BUFSIZ,KEYSIZ) 

C 

C DELETE PRIMARY INDEX AND DATA ENTRY 

INDEX = 

ARRAY(l) = 
50 CALL DELET${FUNIT,BUFFER,PKEY,ARRAY,FLAGS,$300,INDEX,0, 

+ BUFSIZ,KEYSIZ) 
C 
60 CALL TOOUA('ANY MCBE ENTRIES TO DELETE?' ,27) 

READ (1,2222) ANSWER 
C 

IF (ANSWER .EQ. 'Y') GO TO 15 
C ELSE CLOSE UP 

GO TO 444 
C FORMAT STATEMENTS 

1111 FORMAT(6A2) /* PKEY VALUE 

2222 F0RMAT(A2) /* ANSWER 

C 

C ERRCB HANDLERS 

100 CALL TNOUAC ERROR Oti OPEN: STATUS IS: ',24) 

CALL TODEC( STATUS) 

GO TO 444 
200 CALL TOOUC ERROR ON FIND: ',15) 

GO TO 15 
300 CALL TNOUCERRCB CN DELETE ',15) 

CALL TNCXJA( 'MIDAS ERRCB IS:', 15) 

CALL TODEC ( ARRAY (D) 

GO TO 444 /* CLOSE FILE 

C 

444 CALL CLOSM$(FUNIT, STATUS) 
555 CALL EXIT 

END 
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Below is some sample output from an execution of the above program: 

OK, SEG #DELETE 

ENTER PRIMARY KEY VALUE OF RECCKD TO BE DELETED; 9411P 

RECCM) IS: 9411? STUDIO WEST WRCA PALO ALTO 

OKAY TO DELETE?: Y 

ANY MCHE ENTRIES TO DELETE7N 

To verify that the record is really gone, use the READ program: 

OK, SEG #READ 

SEARCH ON PRIMARY? (Y or N) Y 

USE YOUR KEY VALUE? (Y OR N)Y 

ENTER KEY VALUE: 9411P 

PARTIAL KEY? (Y OR N)N 

RETURN ALL DATA? (Y or N) Y 

ERROR ON FIND: 

INDEX IS: 

ARRAY(l) IS: 7 

DO YOU WANT TO CONTINUE? (Y or N)N 



Ihe error code 7 means that the record sought was not found, vdnich was 
certainlv not unexoected. 



DELET$ and Direct Access 

lb delete a record from a direct access file, the user must supply a 
full primary key in key or a floating-point data entry number and data 
entry size in array . 

The only way to delete a secondary index entry from a direct access 
file is to pretend it's not a direct access file and supply the proper 
index number in index instead of the usual value of -1. 
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SECTION 7 
THE CCBOL INTERFACE 



INTRODUCTICaj 

The CCBOL interface to MIDAS is based on the standard CCBOL file I/O 
statanents for INDEXED SEQUENTIAL and RELATIVE files. Ifeyed-index 
MIDAS files are called INDEXED SEQUENTIAL files in CCBOL and direct 
access MIDAS files are known as RELATIVE files. Any kind of MIDAS file 
can be accessed through the CCBOL interface just as if it vere any 
other standard CCBOL INDEXED SEQUENTIAL or RELATIVE file. All the 
"housekeeping" details associated with the FORTRAN call level interface 
to MIDAS are built into both sets of CCBOL file I/O statanents, which 
means that there's no need for the user to worry about them. In 
addition, the COBOL file-handling packages come equipped with 
error-handlers that simplify routine file processing and debugging. 

A tanplate must be created with CREATK for both types of files. COBOL 
cannot "create" a MIDAS file fran program level; it can only access an 
existing file. Any MIDAS file referred to in this section already 
exists; that is, a tanplate has been created for it with c:reatk. 



What's in this Section 

This section explains how to access an INDEXED SEQUENTIAL file frcxn a 
CCBOL program. It describes how to define the file's characteristics 
properly in the various parts of a typical CCBOL program, and explains 
the syntax of the COBOL statanents used to read, write and update 
records in a MIDAS file. Chly INDEXED SEQUENTIAL MIDAS files are 
covered in this section; RELATIVE files are described in Section 11. 

It is assumed that you have previously read Sections 2 and 3 and that 
you already know how to create a template for a keyed-index MIDAS file. 
The syntax and usage of the CCBOL statements and verbs as they pertain 
to INDEXED SEQUENTIAL files are sunnmarized briefly here; refer to The 
CCBOL Fteference Guide for more details on CCBOL syntax and concepts. 
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This section and Section 11 supplonent those portions of The CC60L 
Reference Guide that deal with MIDAS files. This book documents the 
latest version of MIDAS and therefore should be considered the more 
up-to-date of the two books. Fbwever, The CC60L Fteference Guide should 
always be considered the authority on syntax, as this book tends to 
focus only on those aspects of COBOL that apply directly to MIDAS. The 
chief function of sections 7 and 11 is to sunnmarize all the important 
tools vAiich are needed in dealing with MIDAS files. Eterhaps equally 
importantly, they show you how to use these tools in a straightforward 
and practical manner. 



Mare Tterms 

The primary key in an INDEXED SEQUENTIAL file is called the RECORD KEY; 
secondary keys are called ALTERNATE RECORD KEYS. Prime's CCBOL 
supports the use of up to five secondary keys in INDEXED SEQUENTIAL 
files. The primary key in a RELATIVE file is called the RELATIVE KEY 
and is always a record number. Details on RELATIVE file access are 
covered in Section 11. 



Language Dependencies 

VAiile supporting most MIDAS features, CCBOL places these limitations on 
MIDAS files used in CCBOL applications: 

• Up to five secondary keys are supported per file (INDEXED only) . 

• Ihe primary key and all secondary keys (if any) must be included 
in the data record — known as "storing keys in data". 

• The primary key must be the first field in the data record. 

• Secondary keys should not be embedded in the primary key because 
if you change any of the secondary key values, you will impact 
the primary key field which cannot be changed. 

• If a MIDAS file has fixed-length records, the data size 
specified in the level 01 description of the data record must 
match the data size defined for the file during CREATK. 

• The only key types supported by CCBOL are ASCII (A) and bit 
string (B) . Ihe maximun ASCII key size is 64 characters or 
bytes (32 words) ; the maximun bit string key size is 32 
characters (16 words). Avoid specifying any other type of key 
during template creation. 

• Secondary data is not supported (see Appendix C) . 
Restrictions applicable to RELATIVE files are covered in Section 11. 
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Note 



variable-length records. Ibwever, even though the MIDAS file 
template may be declared with variable-length records, CCBOL 
always writes out fixed-length records. 

Compiling and loading a CCBOL Program 

CCBOL programs that access MIEAS files must be loaded with the MIDAS 
library, VKDALB. Ifere is an example of a typical compile and load 
sequence, showing all the libraries that must be loaded in order to 
successfully run a program: 

CCBOL program 

SBG 

VL #program 

LO B_program 

LI VCCBIB 

LI VKDklB 

LI 

SA 

Q 

SEG #program 

You should substitute the appropriate program name for the program 
parameter shown in the above sequence. 

Example ; Ihis is an example of a compile, load and run sequence. 
User input is underlined. 

OK, cobol read .da 
Phase I 
Phase II 
Phase III 
Phase IV 
Phase V 
Hiase VI 



Nd Errors, Nd Warnings, Prime V-Mode COBOL, Rev 17.6 <DACUST> 
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OK, seg^ 

[SEG rev 17.6] 

# vl #read.da 

$ lo b_read.da 

$ li vcoblE 

$ li ykdalB 

$ li 

LOAD COMPLETE 

$ sa 

$ q 

OK, seg #read.da 

ENTER FILE ASSIGNMENTS: 

> (enter filenames or / — see below ) 

FILE ASSIGNMENTS COMPLETE. 

(program now runs — hopefully) 

If the file-id values used in the program to identify existing disk 
files are not identical to the actual pathnames of the files (relative 
to the current directory) , you must indicate v*iich program file-id 
values correspond to v*iich disk files, using the form: 

file-id-value = actual-pathname 

If the file-id-values are identical to the actual filenames of the 
files to be accessed, simply enter a "/" character in response to the 
"ENTER FILE ASSIGbWENTS" prompt as indicated above. For more 
information, see Data Division Requirements, below. 



OPENING A MIDAS FILE 

In order to open a MIEAS file frcxn a COBOL program, the standard COBOL 
file I/O procedures must be followed. The rules for defining an 
INDEXED SEQUENTIAL file in the File ODntrol Section and in the Lata 
Division of a program are discussed below. 



File 03ntrol Requirements 

The File Control paragraph contains the names of the files to be 
accessed, the names of the devices on vAiich they are to be opened, 
optional mode specifications, the names of the primary (RECORD) key 
(one for each file) , the names of any secondary keys (ALTERNATE RECORD) 
present in each file and an optional file status indicator (one for 
each file) to be used in monitoring the success or failure of the 
various program statements that affect each file. 
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The basic fonnat of the SELECT statenent for an INDEXED file is: 

ASSIGN TO PEWS 
ORGANIZATION IS INDEXED 



[ACCESS MODE IS 



SEQUENTIAL 

RANDOM 

DYNAMIC 



RECORD KEY IS key-name-1 

[ALTERNATE RECORD KEY IS key-name-2 [WITH DUPLICATES]...] 

[FILE STATUS IS status-code] . 

For a ccanplete discussion of File Cbntrol Section rules, refer to Ihe 
CCBOL Reference Guide . The important rules are sutmarized below. 

The SELECT Clause ; Simply defines the name of the MIDAS file and tells 
the compiler to assign it some available file unit. Always assign the 
file to PEMS. Indexed files can only be accessed by MIDAS if they are 
disk files. Each filename specified in a SELECT statanent must also 
appear in a Data Division FD entry. (See Efeta Division Recjuir orients, 
below.) 

The Organization Qause ; Is probably the single most important part of 
the File Control definition sequence because it tells the compiler that 
the file to be opened is a keyed-index MIDAS file. 

The ACCESS MODE Clause ; Is optional; the default mode is SEQUENTIAL. 
If SEQUENTIAL is specified, or if the clause is omitted, all reads and 
writes must be performed sequentially — no random operations are 
allowed. Records must be added in primary key order and are always 
retrieved in key order in SEQUENTIAL access mode. 

If the RANDOM access mode is chosen, records can be written and 
retrieved in a random fashion, based on a supplied key value. 
Sequential reads and writes are not permitted. The DYNAMIC access mode 
gets you the best of both modes: yau can read and write sequentially 
or randomly and you can switch back and forth between the two. 

The RECORD KEY Clause ; Defines the key-name associated with the 
primary key Eor the MIDAS file. The parameter key-name-1 must be 
defined in the Record Description entry associated with the PD entry 
for this file, and must be the first entry in such a description. 
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Some general rules of interest governing the RECCM) KEY definition are : 

• A primary key cannot be specified with an OCCURS clauses. 

• No duplicate entries are allowed for the primary key. 

• The length of the primary key cannot exceed 64 characters if 
it's an ASCII key or 32 characters if it's a bit string. It 
must be the same length and type as defined during template 
creation. 

• The primary key cannot have a P character in its PICTURE clause, 
nor can it be defined as a numeric with a separate sign. 

• The primary key should not have secondary keys embedded within 
it because the primary key value cannot be changed. Since 
secondary key values can be altered, it is too easy to get into 

extrone caution. 

• Keys must not be defined in the WCS^KIlsG STORAGE area of the 
program. 

When defining the keys in the File Control section, if you're not sure 
of any of the length or types, use the PRINT option of CREATK to obtain 
a summary of each index description. See Sections 2 or 12 for more 
information. 

The ALTERNATE RECORD KEY Clause ; Designates a field within each record 
as a secondary key. Recall from Sections 1 and 2 that a MIDAS file may 
have secondary keys that are specified during template creation. In 
COBOL, you must always define the keys in the order in v*iich they were 
created during CREATK, that is, index 0, index 1 ... and so on. Ihe 
ALTERNATE RECCM) clause tells COBOL about the order and length of each 
field you've designated as a key for this MIDAS file. A separate 
ALTERNATE RECORD KEY clause is required for each secondary key you've 
defined in the template. The WITH DUPLICATES modifier should be used 
only for those keys v*iich were allowed duplicate status during CREATK 
and is a documentation feature only; you cannot alter the duplicate 
status of an index at program level. This can only be done with 
CREATK; see Section 12 for more information. 

Secondary keys are bound by the same size and type restrictions as the 
primary key and the cannot have P characters in their PICTURE clauses. 
Secondary keys cannot be defined in the WORKING STORAGE area of the 
program either. 

The FILE STATUS Clause ; Names a tvgo-byte unsigned field, called 
status-code in the format above. The COBOL file control system uses it 
to indicate the execution status of each program statement v*iich 
explicitly references the MIDAS file. Each time one of these 
statements is executed, a 2-byte status code is placed into this field 
indicating v*iether or not the operation was successful. Each status 
code describes a different condition or problem, as shown in Table 7-1. 
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Table 7-1. Status Codes for Indexed Files 



Status 


Code 


Error Type 


00 




HWE 


10 




END OF FILE 


22 




INVALID KEY 



23 



30 



90 



91 



92 



93 



INVALID KEY 



SYSTEM I/O 
ERR(» 



Prime-defined 
Conditions are 
codes 90-99 



Interpretation 

Successful ccanpletion of operation. 

End of file reached on READ operation; 
file pointer positioned past logical 
end of file. 

Attempt to perform a WRITE or REWRITE 
viiich vrould create a duplicate primary 
key entry. Duplicate primary key 
values are illegal. 

Record not found on an unsuccessful key 
search; there is no record in the file 
with this key value. 

Operation unsuccessful due to an 

I/O error, such as a data check, parity 

error or a trananission error. 

Record already locked; another 
user or process has already locked 
this record for update. 

Record not locked; a REWRITE operation 
was attempted without first locking the 
record via a READ operation. 

Attempt to add a duplicate secondary 
key value to a secondary index subfile 
that doss not permit duplicates. 

Ihe indexes referred to in the program 
do not match those defined during 
template creation. 



94 



95 



99 



SYSTEM ERRm 



MIDAS concurrency error: another user 
just deleted the record you were trying 
to perform some operation on. 

Bad record lervgth supplied: the 
program has incorrectly specified the 
record length (data size) of the MIDAS 
file. 

System error t could be serious 
trouble. Verify that the program is 
not seriously flawed before you call 
your system analyst. 
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Example ; Below is a sample File Control Section from a program used to 
access the CUSTOMER file created in Section 2. Consult the sample 
program at the end of this section for another example of a File 
Gbntrol Section. 

FILE-CONTOOL. 

SELECT CUSTOMER ASSIGN TO PEMS 

ORGANIZATION IS INDEXED 

ACCESS MODE IS SEQUENTIAL 

RECORD KEY IS CUST-ID 

ALTERNATE RECORD KEY IS CUST-NAME WITH DUPLICATES 

ALTERNATE RECORD KEY IS LOCATION-CODE WITH DUPLICATES 

FILE STATUS IS STATUS-CODE. 
DATA DIVISION. 



Data Division Requirements 

The Data Division of the program describes the record structure of each 
file used in the program, that is, each file mentioned in the File 
Section. It also describes the record structure and data items v*iich 
are not part of external files but viiich are used to handle data 
written to and read from these files during the course of program 
execution. 

The important rules governing the File Section of the Data Division are 
summarized below: 

The File Section of the Data Division consists of the following: 

• One or more file description entries called FD's. If you have 
more than one FD, the keys must be specified in the same order 
in each one. Further, the order in vAiich the keys are described 
in each FD should match the order in which they appear in the 
record . 

• Che or more record description entries for each FD. 

• One or more file-id values, v*iich name the MIDAS files referred 
to in the File Control Section. The file-id value may or may 
not be the same as the filename specified in the File Control 
Section. 
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Ihe general fonnat of a File Description entry is: 
FD filenane [UNCOMPRESSED] 
RECORD IS 



LABEL 



\ 



STANDARD 



RECORDS ARE 

[REC(BD CCKTAINS integer-2 [TO integer-3] CHARACTERS] 
VALUE OF FILE-ID IS file-id-value 



[DATA 



data-name-1 [data-name-2] ...]. 



RECORD IS 
RECORDS ARE 
Here are some important points about the File Section clauses: 



• The FD clause, required for a MIDAS file, must be followed by 
the name \fhich the program uses to refer to this MIDAS file. 
The UNCOMPRESSED option may be specified, but is ignored by 
MIDAS. 

A nX-^^ r Aorr ncv^onr^ to crmxTrNAm^ ^i -«.*^^ ■? ^ ^^^.^i ^^j ^^«- — t t jj—i. 
w Aijc LiTDijij r\ij>-uru-' iO D imvut-uv-f Uiauoc io reCjuireU J-Or CIJ.X QiSN 

files. 

• If the RECORD CONTAINS clause is used, the nunber of characters 
specified must match the data record size specified during 
template creation. The maximun record size is 32767 characters. 

• If the DATA RECCM) clause is used, a record description must 
follow this clause. If more than one DATA RECORD is defined per 
file, a separate description of each one must be given. "Ihe 
beginning of each new record description must begin with an 01 
level number. Multiple record descriptions imply that a file 
has more than one record-type — but all share the same buffer 
area. Ihe key fields must all be specified in the same relative 
order in each DATA RECORD description. Ihis order must 
correspond to the order in vhich the keys were defined during 
template creation. 

• Ihe VALUE OF FILE-ID clause is required; the value of 
file- id-value is used to tie an internal filename to the actual 
name of the MIDAS file as it appears on disk. See Note below. 
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Note 



Since CCBOL only accepts file-id values of 8 characters or 
less, the file-id feature should be used to assign another name 
to any MIDAS file vAiose pathname exceeds 8 characters. The 
actual MIDAS pathname is equated to the internal filename 
(vhich is specified as file-id-value ) at run-time. When CCBOL 
asks for FILE ASSIGNMENTS during run-time, the actual MIDAS 
filename and the file-id value are equated in the form: 

file-id-value = actual -MIDAS-file-pathname 

The actual MIDAS filename may be assigned to file-id-value in 
the VALUE OF FILE-ID clause if it's less than 8 characters. 

Ihe Record Description simply defines all the itons that make up a 
record and their relationship to one another. The complete syntax of a 
Record Description entry is described in the Data Division chapter of 
The CCBOL Reference Guide . 

Example: This example shows a sample File Section in the DATA DIVISICW 
of the program whose Ehviromient Division appeared earlier: 

DATA DIVISION. 
FILE SECTION. 
FD CUSTOMER 

LABEL RECORDS ARE STANDARD 

VALUE OF FILE-ID. IS "CUSTOMER" 

DATA RECORD IS CUST-FILE-RECCRD. 
01 CUST-FILE-RECORD. 

02 CUST-ID PIC X(5) . 

02 CUST-NAME PIC X(25) . 

02 LOCATION-CODE. 

05 REGION PIC XX. 
05 STATE PIC XX. 



The OPEN Statement 

The OPEN statement opens the MIDAS file and establishes the mode in 
vtiich it is to be accessed. It must be executed before any other 
statement that references the file. More than one file can be opened 
with this statenent, but each file name specified in an OPEN statsnent 
must appear in a SELECT and ASSIGN statement and must be described with 
an FD entry in the Data Division. The format is: 



OPEN 



INPUT \ 

I-O > filename 

OUTPUT 



The filename is the internal name for the MIDAS file; INPUT, OUTPUT 

and 1-0 are the access modes which may be applied to the file. (See 
Access Modes below for details.) 
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If the named file cannot be located, the program will abort at 
run-time. This statement may be used to open more than one file as 
shown in this example: 

OPEN INPUT CARD-FILE 

OUTPUT PRINT-FILE, DIRECTORY-FILE. 

Access Modes ; Briefly, here's v*iat you can do in each access mode: 

• In INPUT mode, a file can only be accessed by READ statanents 
("read only" mode) . 

• In OUTPUT mode, a file can only be written to with WRITE 
statements ("write only" mode) . 

• In I-O mode, a file can be both read and written to, and records 
can be updated and deleted as veil. Itecords are automatically 
locked v*ien read in 1-0 mode, vAiereas they are not in INPUT 
mode. (See Record locking later in this section.) 

• ISble 7-2 shows vdiat statanents can be used in each access mode. 



The CLOSE Statement 

Ihe CLOSE statement is the reverse of the OPEN statonent: it tells the 
compiler that the file unit on vhich the file is opened should be 
released and that the file should be written back to disk in its 
current form. The format is simply: 

CLOSE filename 

filename is the name of the file as specified in the SELECT and FD 
clauses. A file can be OPENed and CLOSBd more than once in the same 
program. 
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l^ble 7-2. Statements Permitted in Each Access Made 



INDEXED I/O 



File Access 
Mode 


Statement 


Open Mode 


Input 


Output 


input-Output 


Sequential 


READ 


• 




• 


WRITE 




• 




REWRITE 








START 


• 






DELETE 








Random 


READ 


• 






WRITE 




• 




REWRITE 








START 








DELETE 








Dynamic 


READ 


• 






WRITE 




• 




REWRITE 








START 


• 






DELETE 
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ERROR HANDLING 

Run-time errors can be handled in a nunber of vays. Among them, those 
well-suited to MIDAS file processing are: 

• the AT END clause, v*iich directs control to some "end-of-file" 
handler (procedure) in the event that a logical end of file is 
reached durir^ a read. 

• TQie INVALID KEY clause, v*iich is executed v*ien an error occurs; 
it transfers program control to a designated procedure or 
performs some useful action or series of actions. (Can be used 
in START, READ, WRITE, REWRITE and DELETE statements.) 

• The USE AFTER ERROR statonent viiich indicates the name of a 
procedure in the program which will be executed in the event of 
an I-O error, in addition to the System's standard I-O 
procedures. 

A brief explanation of how these error-handlers work follows; refer to 
The COBOL Reference Guide for complete details on these error handling 
mechanisms. 



The AT END Clause 

The AT END clause, used only in a sequential READ statement, prevents 
program failure vdien an end-of-file condition is encountered during the 
read. Ihe format is simple: 

AT END imperative-statement 

ll^e imperative-statement , for example, could be a GO TO that transfers 
control to another procedure in the program v*iich performs some further 
useful action, or it might simply close the file. Of course, this 
statement could be any number of things; these are just a few 
suggestions. 



The INVALID KEY Clause 

Many things can go wrong in MIDAS file processing, as evidenced by 
Table 7-1. The INVALID Pfey clause is one good way to identify and trap 
these errors. It should be used in all START, READ, WRITE, REWRITE, 
and DELETE statanents to protect your program from key errors. 
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Without an INVALID Key clause or a USE AFTER statement, the program 
will abort vAien a file I-O error occurs. The format of the clause, 
v*iich can be appended to any of the statements mentioned above is: 

INVALID [KEY] imperative-stat«nent 

Ihe word "KEY" is optional: INVALID is sufficient. When this clause 
is executed, the cause of the error may be determined by examining the 
FILE-STATUS variable. For a list of codes, see Table 7-1. 

For example, this READ statement is "protected" by an INVALID KEY 
clause : 

READ MFILE KEY IS PKEY INVALID KEY PERFORM READ-ERRCR. 

If a key error in the MIDAS file MFILE is raised during this READ, a 
procedure named READ-ERROR will be performed. 



The USE AFTER Statement 

The USE AFTER statanent must be placed under the DECLARATIVES section 
of the program, immediately following a section header (and a period 
and a space) . It defines a procedure viiich will be executed in 
addition to the standard 1-0 control system's method of dealing with 
1-0 errors. 



The format of USE AFTER is; 
USE AFTER [STANDARD] I 



I exception) 

[ERROR j mOCEDURE ON 



filename 
INPUT 
OUTPUT 
1-0 



The INPUT, OUTPUT, I-O, and filename parameters are used to indicate 
vAien that particular procedure should be executed. When filename is 
specified, only errors occurring v*iile processing that file will be 
handled by this procedure. This is useful for multi-file processing. 
USE AFTER itself is never executed: instead, it identifies the 



conditions under vvhich the procedure it introduces should be 
Ihe terms EXCEPTION and ERROR are synonymous. 

PROCEDURE DIVISION. 
DECLARATIVES. 



executed . 



Section-name SECTION. USE AFTER etc. 
[paragraph-name, [sentence] ...]... 



REV. 



14 



IDR4558 THE COBOL INTERFACE 



After the execution of the USE procedure, program control is returned 
to the statement following the invoking statement. Ihis example shows 
a simple USE procedure: 

PROCEDURE DIVISIOJ. 
DECLARATIVES. 

ERROR-HANDLING SECTION. USE AFTER ERROR PROCEDURE ON I-O. 
REAE^ERR. 

DISPLAY 'STATUS CODE IS:' ERROR-STATUS. 



etc. 

END DECLARATIVES. 

You can have a separate USE AFTER procedure for each file accessed in 
the program: or, you can have a single procedure for each OPEN mode, 
that is, one for INPUT errors, one for OUTPUT errors, and one for 1-0 
errors (covers everything) . Alternatively, you can have a single USE 
AFTER that handles all the errors that might occur on any of the files 
accessed by the program. 



POSITIONING THE FILE 

The concepts of "file position" and the "current record" are very 
important vstien dealing with MIDAS files. It's a good idea to 
understand them before you attempt to figure out how the actual I/O 
statements work — it will spare you a lot of confusion later on. 



A logical View 

Fran the user's point of view, "file position" refers to the file 
pointer's present position in the file. The record to which it is 
currently pointing is the "current record" . The COBOL statements v*iich 
alter the current record location are OPEN, START, READ and DELETE. 
DELETE alters the current record pointer by leaving the current record 
position undefined after a record is deleted, fbwever, this is no 
problan because it's still possible to do a sequential or keyed READ 
after a DELETE. 
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What's Really Happening 

The first and most important thing to understand is that file 
positioning is actually done relative to a primary or secondary index 
subfile. The user sees file positioning in terms of the data subfile, 
that is, in terms of which record is returned at any given point; 
however, the file position is actually based on v*iich key the user 
supplies in a given START or READ statement. If you specify that a 
START should be done using the primary key (the RECORD KEY) , file 
position will be established via the primary index subfile. If the 
file is then processed sequentially, data subfile records will be 
returned in primary key order; in other words, MIDAS uses the order of 
entries in the primary index subfile as a basis for finding and 
returning data subfile records. 

Similarly, the secondary index subfile can be used as a basis for file 
processing if a secondary key value is used in a START or a keyed READ. 
A sequential read thereafter would return the next data subfile record 
as referenced by the next sequential entry in the secondary index 
subfile. Remanber that MIDAS always adds entries to the index subfiles 
in sorted order; that is, it inserts things v^iere you vould logically 
expect them to be inserted. That's v*iy it always seems that records 
are in some logical order, when they are really just stored in the 
order in vdiich they were written. 



Record Lacking 

Record locking is another important concept in MIDAS that applies to 
files opened for I-O only, lb protect users fran conflicting updates 
and to ensure that the record you just read will be the record you 
update or delete (assuning you want to perform either of these 
operations) , the READ statement always locks the record to v^iich it 
positions. Remanber, this happens only in files opened for I-O. When 
a record is "locked", it beccxnes, in a sense, the sole property of the 
user v\*io locked it, protecting the record from harm by any other user 
as long as the record remains locked. This is a general rule, and of 
course, there are always exceptions. {One such exeception is described 
under START and Lpcked Records , below.) The record remains "locked" 
until another I/O operation is performed. Cnly the "current record" 
can be locked and READ is the only CCBOL statonent that can lock a 
record. There are no specific "lock" and "unlock" statements in CCBOL. 

What If Somebody Else... : If your program attempts to access a record 
vtiich someone else has already locked, a MIDAS error will occur. If 
you don't have a "program trap" for this condition, the code of a MIDAS 
error message will appear at your terminal and the program will abort. 
In addition, a file status code of 90 will be returned. Tb be safe, 
make sure that your program handles all the file status conditions 
listed under File Status codes in TSble 7-1. For details, see ERROR 
HANDLING, above. 
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The START Statement 

Itie START statement establishes file position in a MIDAS file opened 
for SEQUENTIAL or DYNAMIC access by moving the file pointer to a 
specific record in the file. START cannot be used in a file opened for 
RANDOM access. 

Generally, START uses a specific key value or a conditional expression 
based on a key value to position a MIDAS file to a particular record. 
If an explicit key value is not supplied by the progran, the primary 
key (the RECORD KEY) is assumed. Tb position the file on an explicit 
key value, follow these two steps: 

1. Use a MOVE statanent to assign some initial value to the key 
you want to use in the START operation. 

2. Use a START statement to specify v*iether the file should be 
positioned to the first record containing that key value or to 
the first record with a key value greater than the value just 
M0VB3 to that key, or to the first record with a key value 
greater than or equal to the specified key value. 

The general format of START is: 



START filename [KEY IS 



GREATER THAN 
NOT LESS THAN 
EQUAL TO 



Key-name] 



[ INVALID KEY imperative-statement] . 

key-name is the name of a file key (which must have been defined in the 
RECORD definition) and contains some value previously assigned by a 
MOVE operation. The value in key-name is used for comparison by the 
START statement. The INVALID KEY clause must be included unless a USE 
AFTER procedure has been provided for this file under the DECLARATIVES. 

]Jnportant Fbints : The important points to note about START are: 

• START only positions the file pointer — it does not return the 
record (as in a READ) . 

• START can only be used with files opened for SEQUENTIAL or 
DYNAMIC access. 

• If the key value specified in the previous MOVE does not exist, 
the program will terminate abnormally unless sane error-handling 
mechanism is included in the program. See ERROR HANDLING above. 

• Both primary and secondary key values can be used to position 
the file, but a value must be assigned either to the RECCf® KEY 
(primary key) or to an ALTERNATE RECORD KEY (a secondary key) 
prior to the START statement. If a secondary key is used, the 
KEY IS key-name clause must be included in the START statement. 



- 17 October 1980 



SECTICN 7 IDR4558 



• The GREATER THAN option positions to the first file record vAiose 
key value is greater than that assigned to key-name . 

• Ihe NOT LESS THAN option positions to the first record with a 
key-name value that is equal to or greater than the value 
assigned to the indicated key. 

• If key-name is a primary key, or is a secondary key that does 
not allow duplicates, the EQUAL TO option positions to the 
record in which that key field value is the same as the value 
assigned to key-name. 

• If key-name is a secondary key that does allow duplicates, the 
EQUAL TO option will position to the first record with the 
indicated key value. 

• START does not lock the record to v*iich it positions. 

Slfe^ and Lacked Records ; If you attempt a START operation on a i::ec^ d 



that i"&">a^eady locked by another user, here's v*iat will 
f i Le-status^3<«^ of 90 will be returned, you will (mijairentionallV) 
urlock the recorSKfor the other user, and your fyre''i»sition wi^l 
remain unchanged. Tto--.^ke matters more inteteSting, the person 
originally locked the record>^ll subsequently get a 91 error v^en 
M]nAS attempts to unlock thisalT?€|^y--t3nlocked record. 

In spite of all this^-^-tfie original cQi^c^nt record position remelins 
ur:;hanged File posi-fei^n is thus unaffected bySh-S^^^T that encounters a 
locked recor^...----^'^ another START is attempted, you*^!:! — get the reiord 
you want,.,MriIess the other user (for vAiom you unlocked the^^eogrd) b^ts 
yojaJfecTit. 

Out of Range Keys ; If you specify a key value that causes START to 
position the file pointer to the end of the file, for example, START 
KEY IS GREATER THAN AGE \^*iere the AGE field has been initialized to its 
largest value in the file, the "end-of-file" condition will be raised 
by a subsequent READ. Ihis makes sense because it is not an error to 
position the file pointer to erxJ-of-f ile , but it is not possible to 
read beyond the last file record. 

Examples : Generally, to process a file sequentially via some index, 
first set the file pointer to the beginning of that index this way: 

MOVE LOW- VALUES TO key-name. 

START filename KEY IS NOT LESS THAN key-name 

INVALID KEY GO TO KEY-ERR. 

or 

MOVE SPACES TO key-name 

START filename KEY IS NOT LESS THAN key-name 

INVALID KEY GO TO KEY-ERR. 
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On page 7-19, the phrase KEY IS should be inserted after PHONE-FILE 
in the example at the tC3p of tiie page. 
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"lb set file position with a particular key value, simply move that 
value to the proper key field, as in: 

MOVE '617' TO AREA-CODE. 

START PHONE-FILE, NOT LESS THAN AREA-CODE INVALID KEY GO TO ERRORS. 

Positioning on Partial Keys ; can be done in SEQUENTIAL or DYNAMIC 
modes only, using the MOVE and START statements. The GREATER THAN and 
NOT LESS THAN options enable the use of partial key values in 
positioning the file pointer as long as the key value is correctly and 
fully initialized before the START statanent is executed, Ihis applies 
to both primary and secondary keys. For example, using the CUSTOMER 
file, if you wanted to find all the records whose CUST-NAME fields 
begin with the letter F and above, you might initialize the file 
position as shown in this program excerpt: 

PROCEDURE DIVISIOJ. 
FIRST-moC. 

OPEN INPUT CUSTOMER. 

MOVE 'F' TO CUST-NAME. 

START CUSTOMER KEY IS NOT LESS THAN CUST-NAME 

INVALID KEY GO TO KEY-ERR. 



File reads can be divided into tWD basic categories: sequential and 
keyed . 

Sequential reads simply mean reading one record after the other in 
primary key or secondary key order depending on which index the file is 
positioned on. In this type of read, the user doesn't supply a key 
value except to tell MIDAS at vAiich point in the index to start reading 

Keyed reads are also called "randan" reads because it is possible to 
jump anyv*iere from the current file position by specifying a new key 
value to search for. 



Access Msdes 

The three types of access modes possible in CCBOL — DYNAMIC, RANDOM 
and SEQUENTIAL — were mentioned earlier. Each access mode permits 
only certain operations to be performed on a file. Keyed reads are the 
only type of read possible in RANDOM access mode, while sequential 
reads are the only type permitted in SEQUENTIAL access mode. DYNAMIC 
access mode allows the user to switch from one type of read to another, 
that is, you can do a keyed read to get to a certain spot in an index 
area then do sequential reads from there to retrieve the records viiich 
logically follow it. 
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Reminder ; You must have the file open for INPUT or I-O in order to 
read iti 



Sequential Reads 

Sequential reads vork by positiong the file to the next logical record 
in after the current record, making it current. This record is then 
read and returned to the user. This implies the need for a current 
record as a reference point. The current record is established by a 
MOVE and START or by a previous READ operation. Sequential reads are 
legal in SEQUENTIAL and DYNAMIC access modes, but not in RANDOM mode. 

In SEQUENTIAL Access Mode : You can read the file sequentially by 
primary or secondary key. Records cannot be read randcxnly. 

The format of a sequential READ statement in SEQUENTIAL access mode is: 
READ filename [INTO read-var] 
[AT END imperative-statement] . 

The optional INTO clause reads the record retrieved by the READ 
operation into read-var . If omitted, the record value is returned in 
the buffer associated with the file in the FD. Ihe AT END clause must 
be included in each READ statenent unless an applicable USE AFTER 
procedure has been specified for this file under the DECLARATIVES. The 
NEXT RECCRD clause is implied but not stated in this format because 
every READ operation in SEQUENTIAL access mode automatically performs a 
position to the next record in the file before the READ is performed. 
Records are not locked vvhen read if the file is opened for INPUT only; 
however, they are locked if the file is opened for I-O. Furthermore, 
the current record ranains locked until another I/O operation is 
performed, yielding a new current record. 

Ihe following excerpt from a CCBOL program written to access the 
CUSTOMER file shows the PROCEDURE DIVISION which reads the file 
sequentially, in primary key order. 

mOCEDURE DIVISION. 
FIRST-PROC. 

OPEN INPUT CUSTOMER. 

MOVE LOW-VALUES TO CUST-ID OF CUST-FILE-RECORD. 
START CUSTOMER KEY IS NOT LESS THAN CUST-ID 
INVALID KEY GO TO END-FILE. 
READ-LOOP. 

READ CUSTOMER NEXT INTO READ-REC AT END GO TO END-FILE. 
DISPLAY READ-REC. 
GO TO READ-LOOP. 
END-FILE. 

CLOSE CUSTOMER. 

IF STATUS-CODE =00 DISPLAY ' SUCCESSFUL CCMPLETION. ' 

ELSE 

DISPLAY 'STATUS CODE IS:' STATUS-CODE. 

STOP RUN. 
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In DYNAMIC Access Mode ; You can read a file sequentially by primary or 
secondary key simply by using the NEXT clause. The key on vhich the 
READ is done could be established by a START or by a keyed read (see 
Keyed Reads , below) . Chce the file position is established (relative 
to a primary or secondary index) , you can read the file sequentially, 
by index entry order, with this form of the READ statement: 

READ filename NEXT RECCM) [INTO read-var] 
[AT END imperative-statanent] . 

Ihe AT END clause is used to trap end-of-file corx3itions, and must be 
specified if there isn't an applicable USE AFTER procedure under the 
DECLARATIVES. PDr example, if the CUSTOMER file is opened for I-O in 
DYNAMIC access mode, records can be read sequentially from some point 
in a primary or secondary index by just using START, then a READ NEXT 
statement : 

PROCEDURE DIVISION. 
FIRST-FROC. 

OPEN INPUT CUSTOMER. 
MOVE LOW-VALUES TO CUST-ID. 
START CUSTOMER KEY IS NOT LESS THAN CUST-ID 
INVALID KEY GO TO KEY-ERR. 
READ-NEXT. 

READ CUSTOMER NEXT RECORD INTO REAE^REC 

AT END GO TO KEY-ERR. 
DISPLAY 'READ NEXT AFTER START RETURNS FIRST LOG. RECORD' . 
DISPLAY READ-REC. 
READ-CUR. 

DISPLAY 'RKAD WITH "KEY IS" RETLPxNS CUPJ'.ENT RECORD' . 
READ CUSTOMER INTO READ-REC KEY IS CUST-ID 
INVALID KEY GO TO KEY-EPJ^, 
DISPLAY READ-REC. 
READ-RANDCM. 

MOVE 'FLORA PORTRAITS ' TO CUST-NAME. 

READ CUSTOMER INTO READ-REC KEY IS CUST-NAME INVALID KEY 
GO TO KEY-ERR. 

DISPLAY 'RANDOM READ ON SECONDARY KEY:' READ-REC. 
DISPLAY ' NOW READ SEQUENTIALLY ON THIS SECONDARY INDEX' . 
READ-LOOP. 

READ CUSTOMER NEXT RECORD INTO REAI>-REC AT END 

GO TO FINIS. 
DISPLAY READ-REC. 
GO TO READ-LOOP. 
KEY-ERR. 

DISPLAY 'STATUS CODE IS:' STATUS-CODE. 
GO TO CLOSE-FILES. 
FINIS. 

IF STATUS-CODE = 00 DISPLAY "NO ERRORS' 
ELSE DISPLAY 'STATUS CODE IS:' STATUS-CODE. 
CLOSE-FILES. 

CLOSE CUSTOMER. 
STOP RUN. 
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Ihis program segment would read the entire file by secondary key 
(CUST-NW»1E) and would handle the end-of-file condition by transferring 
control to the FINIS label. 



Keyed Reads 

Keyed (randcxn) reads are performed simply by specifying the key value 
on v*iich a search should be conducted. Keyed reads are legal in RANDOM 
and DYNAMIC access modes and work the same way in each mode: move the 
key value into the proper key field, then use this form of the READ to 
position to and retrieve the desired record: 

READ filename [RECORD] [INTO read--var] 

[KEY IS key-name] 

[ INVALID KEY imperative-stmt] . 

Ebr example, to retrieve a record for the CUSTOMER file with a CUST-ID 
value of '2194G', the program logic might be: 

PROCEDURE DIVISION. 
FIRST-PROC. 

OPEN INPUT CUSTOMER. 

MOVE '2194G' TO CUST-ID OF CUST-FILE-RECORD. 
READ-RANDOM. 

READ CUSTOMER INTO READ-REC KEY IS CUST-ID 

INVALID KEY GO TO KEY-ERR. 

DISPLAY READ-REC. 

A keyed read does not require, and in fact eliminates the need for, a 
START operation. In fact, STARTS are illegal in RANDOM access mode, 
vAiich only allows keyed reads anyway. In RANDOM access mode, any READ 
done without the KEY IS clause automatically returns the current 
record, that is, the record to y*iich the file pointer is pointing at 
the time the READ operation is encountered. It is not legal to MOVE 
LOW-VALUES to a key field prior to a keyed READ in RANDOM mode because 
there is no key value that matches LOW-VALUE (octal 200) in a MIDAS 
index subfile. 



Changing Search Indexes 

The "KEY IS" clause provides an easy method of switching from one index 
subfile to another without using a START. Simply put the key value you 
want to search into the proper key-name variable, then use that 
key-name in the KEY IS clause. This will establish key-name as the new 
"key of reference" and will automatically put you into the 
corresponding index subfile. 
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Reading Duplicates 

For secondary keys that allow duplicates, it is possible to retrieve 
all the records with the same secondary key value in DYNAMIC access 
mode only. Follow these steps: 

1. MCfVE the desired secondary key value into the appropriate 
secondary key: 

MOVE "sec-val* TO sec-key-name 

2. Position the file with a START to the first record with this 
key value: 

START filename NOT LESS THAN sec-key-name INVALID KEY 
imperative-statement . 

3. In a loop, use a READ NEXT statement with the AT END option to 
trap the end-of-file condition (status code 10) which happens 
v*ien there are no more entries in the index to search. 

4. Compare the value just read with the value sought to verify 
that it is indeed a valid duplicate. 

For example : Using the CUSTOMER file, suppose you want to read all the 
records \mich have the value WRCA in their LOCATION-CODE field (a 
secondary key) . Position the file by secondary key to the first WRCA 
entry in secondary index subfile 02, then READ NEXT in a loop until no 
more duplicates are found. Ihe following is the moCEDURE DIVISION of 
a program that accesses duplicate values in the CUSTOMER file: 

PROCEDURE DIVISION. 
FIRST-DUP. 

OPEN INPUT CUSTOMER. 
Muvr. 'vvni.,/i- TO L,OC/\TiuN-CODt;, 
START CUSTOMER KEY IS NOT LESS THAN LOCATION-CODE 
INVALID KEY GO TO KEY-ERR. 
READ-LOOP. 

READ CUSTOMER NEXT RECORD INTO READ-REC 
AT END GO TO KEY-ERR. 

IF LOCATION-CODE NOT EQUAL 'WRCA' GO TO FINIS. 
PRINT-REC. 

DISPLAY READ-REC. 
GO TO READ-LOOP. 
KEY-ERR. 

IF STATUS-CODE = 10 DISPLAY 'END OF FILE' 
ELSE 

DISPLAY 'STATUS CODE IS:' STATUS-CODE. 
FINIS. 

CLOSE CUSTOMER. 

IF STATOS-CODE = 00 DISPLAY 'ALL DONE' . 

STOP RUN. 

When run, the program prodixres the following output: 
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9411PSTUDIO WEST 


WRCA 


9402AARTIS'mY UNLTD. 


WRCA 


2334PSEACCftST STRIPPERS 


WRCA 


END OF FILE 




AT.r, DC»}E 




OK, 




More on Partial Key Access 





Partial key access is possible only by using the MOVE and START 
statenents — partial values cannot be used in READ operations. 
HDwever, the MOVE and START statements provide a good method of 
searching for values less than or greater than a particular value. The 
value itself may represent a full or partial key value. By partial key 
value, we 4nean a prefix of a full key value. Ebr example, if a key 
value is "FLORA", legal prefixes would include: "P, "FL", "FLO", and 
so forth. The use of partial key values in positioning the file vas 
introduced earlier, and this example shows how this concept can be 
applied in a typical situation: 

PROCEDURE DIVISIC»J. 
FIRST-FROC. 

OPEN INPUT CUSTOMER. 

MOVE 'F' TO CUST-NAME. 

START CUSTOMER KEY IS NOT LESS THAN CUST-NAME 

INVALID KEY GO TO KEY-ERR. 
READ-IT. 

READ CUSTOMER NEXT RECORD INTO REAE>-REC AT END 

GO TO FINIS. 

DISPLAY 'FIRST RECCED WITH NAME BEG. WITH F:' 

DISPLAY READ-REC. 

DISPLAY 'READ REST OF RECORDS BEG. WITH F ON UP:' . 
READ- LOOP. 

READ CUSTOMER NEXT RECORD INTO REAE^REC AT END 

GO TO FINIS. 

DISPLAY READ-REC. 

GO TO READ-LOOP. 

When run, the following is printed at the terminal: 

FIRST RECORD WITH NAME BEG. WITH F: 

1002PFLORA PORTRAITS NENY 

READ REST OF RECORDS BEG. WITH F CW UP: 

4056SMARK-BURTC»J NEMA 

2334PSEACOAST STRIPPERS WRCA 

2194GSPECTROGRAPHICS NWOR 

9411PSTUDIO WEST WRCA 



REV. 7-24 



im4558 THE CCBOL INTERFACE 



ADDI^G RBCCKDS 

Records can be added to a MIEAS file vAien it is opened for OUTPUT or 
I-O. Kbwever, a file opened for SEQUENTIAL access can only be written 
to if it's opened for OUTPUT. Ihe WRITE statement takes information 
supplied by the user and adds it to the MIEAS file. Regardless of the 
order in viiich the records are presented, MIDAS inserts all primary key 
entries into the primary index subfile in ascending key sequence (low 
values first) ; however, the data records are always added to the 
bottom of the data subfile. Secondary key entries, like primary key 
entries, are added to secondary index subfiles in sorted order. 
Duplicates are handled a bit differently; vhen MIDAS first attonpts to 
add a duplicate entry (for a secondary index that allows duplicates) it 
sets a flag in the original entry to indicate that there's more than 
one occurrence of this particular entry value in the index subfile, 
mplicates are added sequentially thereafter, following the last 
matching key. 



The WRITE Statanent 

A unique key value must be supplied for the primary key of each record 

added to ^n TMrEXFri CPntTET^TfTAT -FiTo Ti^ ^t-V^a'^ T.iK^^^e; ^.,*. a .,_i.._ 

in the RECORD KEY (primary key) field before each WRITE statement is 
executed. lb add secondary keys to their respective indexes, put the 
appropriate values in the secondary key fields prior to the execution 
of the WRITE statement. Ihe WRITE statement format is: 

WRITE record-name FROM frcm-area 
[INVALID KEY imperative-Statement] . 

Ihe important things about this statanent are: 

• In fixed-length files, if the data in from-area is not the same 
length as the file record, it is truncated or blank-filled. 

• Make sure from-area and record-name do not reference the same 
memory location. 

• A unique value for the primary key must be supplied prior to the 
execution of each WRITE. 

• The INVALID KEY clause can be used to trap duplicate primary or 
secondary key errors and is required unless a USE AFTER 
procedure is specified for this file in the DECLARATIVES. 
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In files open for SEQUENTIAL access, the data values to be added should 
be supplied in sorted order, by primary key value. Because the file 
pointer cannot be randanly positioned in SEQUENTIAL access, the entries 
cannot be added randomly either. Hawever, it's okay in the other 
access modes to give unsorted input to the program, although it just 
makes good sense (and better performance too) to sort it vi*ierever 
possible. 

WRITE Example ; This program shows how to add entries to a file 
interactively by prompting the user for input, then inserting the entry 
into the file. "Ihis is a case v\*iere you can't always be sure of the 
order of input entries, so the file is opened for DYNAMIC access mode: 

ID DIVISION. 

PROGRAM- ID. AID-PROG. 

AUTHOR. LJD. 

INSTALLATION. TPUBS. 

DATE-WRITTEN. 08/28/80. 

DATE-CCMPILED. 08/28/80. 

SECURITY. NONE. 

REMARKS. PROGRAM TO TEST CUSTOMER FILE ADDS. 

ENVIRONMENT DIVISION. 

C»]FIGURATION SECTION. 

SOURCE COMPUTER. PRIME. 

CBJECT COMPUTER. PRIME. 

INPUT-OOTPOT SECTION. 

FILE-CC»1TR0L. 

SELECT CUSTOMER ASSIGN TO PFMS 
CBGANIZATION IS INKIXED 
ACCESS MODE IS DYNAMIC 
RECORD KEY IS CUST-ID 

ALTERNATE RECORD KEY IS CUST-NAME WITH DUPLICATES 
ALTERNATE RECORD KEY IS LOCATION-CODE WITH DUPLICATES 
FILE STATUS IS STATUS-CODE. 
DATA DIVISION. 
FILE SECTION. 
FD CUSTOMER 

LABEL RECORDS ARE STANDARD 
VALUE OF FILE-ID IS "CUSTOMER" 
DATA RECORD IS CUST-FILE-RECORD. 
01 CUST-FILE-RECORD. 

02 CUST-ID PIC X(5) . 
02 CUST-NAME PIC X(25) . 
02 LOCATION-CODE PIC X(4) . 
02 FILLER PIC X(35) . 
WORKING-STORAGE SECTION. 
01 STATUS-CODE PIC 99. 
01 READ-REC PIC X(35) . 
PROCEDURE DIVISION. 
FIRST-PROC. 

OPEN I-O CUSTOMER. 
GET-DATA. 

DISPLAY 'ENTER CUSTOMER ID ~ PIC X{5) OR ENTER XX TO QUIT' . 
ACCEPT CUST-ID. 
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IF CUST-ID = 'XX' GO TO FINIS. 
CHECK-DUPS. 

READ CUSTCMER KEY IS CUST-ID 

INVALID KEY GO TO CHECK. 
GET-REST. 

DISPLAY • ENTER CUST-NAME — 25 CHARS' . 

ACCEPT CUST-NAME. 

DISPLAY 'ENTER LOCATION CODE — 4 CHARS (REGION-STATE) ' . 

ACCEPT L0CATIC»I-CODE. 

WRITE CUST-FILE-RECCfftD INVALID KEY 
GO TO CHECK. 

GO TO GET-DATA. 
CHECK. 

IF STATUS-CODE = '23' GO TO GET-REST 
ELSE DISPLAY ' STATUS-CODE IS:' STATUS-CODE. 

GO TO GET-DATA. 
FINIS. 

IF STATUS-CODE = 00 DISPLAY 'ALL DONE' 
ELSE 

DISPLAY 'STATUS CODE IS:' STATOS-CODE. 

CLOSE CUSTOMER. 

STOP RUN. 

When run, the program does the following (user input is underlined) : 

RNTRR CU'^TXIMPR rn _ _ vnn yic\ np pvimpn w wn, r\nTm 

8888T 

ENTER CUST-NAME —25 CHARS 

MARVIN'S TYPESETTING 

ENTER LOCATION CODE ~ 4 CHARS (REGION-STATE) 

SWAZ 

ENTER CUSTOMER ID - - PIC X(5) OR ENTER XX TO QUIT 

XX 

ALL DONE 

OK, 

To verify that the new record was added and was inserted in the proper 
order, run the program shown earlier that reads the file sequentially 
by primary key: 

OK, seg #seqrd 

ENTER FILE ASSIGNMENTS: 

> / 

FILE ASSIGNMENTS COMPLETE. 

0816a*torrow I^per Mills NENH 

1002PFLORA PORTRAITS NENY 

2194GSPECTROGRAPHICS NWOR 

2334PSEACOAST STRIPPERS WRCA 

405691ARK-BURTasi NEMA 

8888TMARVIN'S TYPESETTING SSWA 

9402AARTIS'mY UNLTD. WRCA 

9411PSTUDIO WEST WRCA 

SUCCESSFUL COMPLETiraJ. 

OK, 
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UPDATING RECORDS (REWRITE) 

A record update in CCBOL consists of rewriting the entire record. Any 
field can be changed, with the exception of the primary key field. 
Because a record must be locked in order to be updated, only the 
current record can be updated. In SEQUENTIAL access mode, you must 
first READ the record to indicate vAiich one is to be rewritten. In 
RANDOM mode you must position to the record with a keyed read; in 
DYNAMIC mode, either of these methods will do. If the record to be 
updated is not read prior to a REWRITE, a status code of 91 will be 
returned. This condition code indicates an unlocked record; a record 
must be locked in order to be updated. In addition, the file must be 
open for I-O: this applies to all access modes. 



The REWRITE Format 

The REWRITE statement format is the same for all access modes The 
INVALID KEY clause must be included in all REWRITE statonents if there 
is no USE AFTER procedure specified for this file under the 
DECLARATIVES. 

REWRITE record-name [FROM frcxn-area] 
[ INVALID KEY imperative-statement] . 

If the FROM option is used, the RECCff^ KEY value must be the same as 
the key used in the previous READ. This option allows the new record 
to be written frcxn another file or data area. The data in this "FROM 
area" is moved to the record-name buffer before it is written to the 
file. Without the FROM option, you directly modify the buffer 
( record-name ) v*iich contains the just-read data and then write it back 
to the file. 

PROCEDURE DIVISIOSI. 
FIRST-FROC. 

OPEN 1-0 CUSTOMER. 

MOVE • 2334P' TO CUST-ID. 
RFAD— THI S 

READ CUSTOMER INTO READ-REC KEY IS CUST-ID 

INVALID KEY GO TO KEY-ERR. 

DISPLAY 'CURRENT RECCM) IS:' READ-REC. 
CHANGE-VAL. 

MOVE ' 2334PSEACOAST FINISHERS WRCA' TO NEW-RECCKD. 

UPDATE. 

REWRITE CUST-FILE-RECORD FRCM NEW-RECORD 

INVALID KEY GO TO KEY-ERR. 

READ CUSTOMER INTO READ-REC INVALID KEY 

GO TO KEY-ERR. 
DISPLAY 'UPDATED RECORD IS:' READ-REC. 
ALT-UPDATE. 

MOVE NEW-RECORD TO CUST-FILE-RECORD. 
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REWRITE CUST-FILE-RECCM) INVALID KEY GO TO KEY-ERR. 

GO TO FINIS. 
KEY-ERR. 

DISPLAY 'STATUS CODE IS:' STATUS-CODE. 
FINIS. 

When run, the program produces the following output: 

CURRENT RECORD IS:2334PSEACCAST STRIPPERS WRCA 
UPDATED RECORD IS : 2334PSEACQAST FINISHERS WRCA 
ALL DOIE 
OK, 



DELETING RECORTS 

The DELETE statement in COBOL removes the data record and its primary 
index entry and marks all the corresponding secondary index entries for 
deletion. The space occupied by these secondary index entries is not 
reclaimed until the MPACK utility is run on this file. Rananber that 
the file must be opened for I-O in order to delete entries from it. 



The DELETE Statanent Format 

The DELETE format is: 

DELETE filename [INVALID KEY imperative-stmt] . 

filename is the name assigned to the MIDAS file in the SELECT clause 
and FD clause. The INVALID KEY clause must be included in the DELETE 
statanent v*ien the file is opened for RANDOM or DYNAMIC access and 
there is no USE AJTER procdure specified for this file. Eto not include 
the INVALID KEY clause in DELETE statonents used on files opened for 
SEQUENTIAL access. 

The important things to remember are: 

• In SEQUENTIAL access mode, the record must first be read in 
order to be deleted. This is because a EELETE operation in 
SEQUENTIAL access mode does not perform a position operation : 
that's v*iat the READ is for. 

• In SEQUENTIAL access mode, the value in the RECORD KEY (the 
primary key) should not be changed between the READ and the 
DELETE statements. This is because DELETE can only operate on 
the current record and uses the primary key value used in the 
READ to check that it's the same one as the current record's 
primary key value. 
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• In DYNAMIC and RANDOM access modes, if the record for v*iich a 
prior key value has been supplied cannot be found, the INVALID 
KEY clause will be activated and a file status code of 23 will 
be returned. 

• A DELETE operation leaves the current record undefined, but a 
READ NEXT or a keyed read operation iirmediately after a EELETE 
will be successful, assuming that you didn't delete the last 
record in the file. 

• You can't perform two EELETEs in a row in SEQUENTIAL access 
mode , but you can in RANDOM or DYNAMIC modes , as long as you 
supply a new primary key value. 



Ifew to Ranove Records 

lb delete records in files opened for RANDOM or DYNAMIC access, MOVE 
the primary key value of the record to be deleted to the RECORD KEY. 
The DELETE statement then positions to this record and deletes it. In 
RANDOM and DYNAMIC access modes, DELETE automatically locks the record 
upon positioning to that record. Ihis makes that record the current 
record. In SEQUENTIAL access mode, the record must be read prior to a 
DELETE to establish the current record position because DELETE does not 
perform a position operation in SEQUENTIAL access mode. 



Nate 

If you attanpt to read a record that has been deleted from a 
file, you'll get a 23 error (record not found). However, a 
subsequent READ NEXT will return the next record (in key order) 
that happens to follow the current record. 



Examples 

The first of these two examples shows the PROCEDURE DIVISION of a 
program that accesses the CUSTOMER file when opened for DYNAMIC access. 
The second program shows how to delete a record from the CUSTOMER file 
v*en it is opened for SEQUENTIAL access. 
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Program Excerpt 1 ; 

mOCEDURE DIVISION. 
FIRST-PRCX:. 

OPEN I-O CUSTOMER. 
MOVE ' 0816S' TO CUST-ID. 

DISPLAY 'DELETE RECCKD WITH PRIMARY KEY 0816S' . 
DEL-REC. 

DELETE CUSTOMER. 

READ CUSTOMER NEXT RECORD INTO REAEKREC AT END 
GO TO KEY-ERR. 
DISPLAY "NEXT RECORD IS:' READ-REC. 
GO TO FINIS. 
KEY-ERR. 

DISPLAY 'STATUS COM: IS:' STATUS-CODE. 
FINIS. 

IF STATUS-CODE = 00 DISPLAY 'ALL DONE' 
ELSE DISPLAY 'STATUS CODE IS:' STATUS-CODE. 
CLOSE CUSTOMER. 
STOP RUN. 
OK, 

When run, the program produces this output: 

DELETE RECORD WITH PRIMARY KEY 0816S 

NEXT RECORD IS:1002PFLORA PORTRAITS NENY 

ALL DOIE 
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Program Eiecerpt 2 ; 

PROCEDURE DIVISIOJ. 
FIRST-FROC. 

OPEN I-O CUSTOMER. 
MOVE • 2334P' TO CUST-ID. 

START CUSTOMER KEY IS EQUAL TO CUST-ID INVALID KEY 
GO TO KEY-ERR. 
READ-THIS. 

READ CUSTOMER INTO READ-REC 
INVALID KEY GO TO KEY-ERR. 
DISPLAY READ-REC. 
DEL-REC. 

DELETE CUSTOMER INVALID KEY GO TO KEY-ERR. 
GO TO FINIS. 
KEY-ERR. 

•DISPLAY 'STATUS COEE IS:' STATUS-CODE. 
FINIS. 

IF STATUS-CODE = 00 DISPLAY 'ALL DONE' 
ELSE DISPLAY 'STATUS CODE IS:' STATUS-CODE. 
CLOSE CUSTOMER. 
STOP RUN. 
OK, 

The program produces the following output: 

2334PSEACCIAST FINISHERS WRCA 
ALL DONE 
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SBCTIOI 8 
THE BASIC ■'VM INTERFACE 



INTRODUCTim 

BASIC/VM' s interface to MIDAS consists of a special set of file 
handling statsnents that read, write, delete and update entries in a 
MIDAS file. The MIDAS access statements are similar in format to the 
standard file handling statanents in BASIC/VM, but extensions to their 
syntax permit the more complex operations associated vdth MIDAS files. 
Because the interface acts as a "go-betv\een" , translating the user's 
demands into the MIDAS subroutine calls v*iich do all the vork, a MIDAS 
file can be processed as easily as any other file type supported by 
BASIC/VM. 



Note 

This section assunes that you've read and are familiar with the 
the concepts in Section 1 and 2. In addition, it may be vorth 
clarifying that access to MIDAS files is supported only by the 
BASIC/VM compiler, and not by any of Prime's other BASIC 
sci-L.Vriare prociucus. 



Language Dependencies 

like all other language interfaces (except PI/I) , a tanplate must be 
created for a MIDAS file (with CREATK) before it can be accessed frcxn 
BASIC/VM. In addition, the following rules apply to BASIC/VM' s MIDAS 
interface: 

• l^ to 17 secondary indexes are allowed per file (duplicates are 
allowed) . 

• Qily keyed-index MIDAS files are supported; direct access MIDAS 
files cannot be processed by BASIC/VM. 

• Key fields are not required to be part of the data record, but 
it is strongly recorrmended that they be included. 

• The secondary data feature is not supported . 

"IVo very important things to ronember are: first, that keys are 
referred to by nimber in BASIC/VM; therefore the primary key is KEy0, 
the first secondary is KEY01, the second KEY02, etc.; secondly, that 
key nartoers and index sii>f ile nurtoers are one and the same. Any 
reference to a particular key is implicitly a reference to the index 
subfile in vvhich those key values are stored. 
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Summary of Pccess Statanents 



The BASIC/VM statements needed to process a MIDAS file are briefly 

summarized in T^ble 8-1. Experienced BASIC/VM users will note the 

similarity betveen these statements and those used in handling other 
file types in BASIC/VM. 



OPENING/CLOSING A MIDAS FILE 

BASIC/VM uses the same methods of opening and closing a MIDAS file as 
it does any file — the DEFINE FILE statement. The file type must be 
declared as MIDAS. 



The DEFINE FILE Statement 

Ihe EEFINE FILE statanent opens a MIDAS file and assigns it a file unit 
number to be used as an alias for the file for the remainder of the 
program. Up to 12 files can be opened at a time frcxn a single BASIC 
parogram. Be sure to use the unit numbers 1-12 v*ien opening a MIDAS 
file. The keyword MIDAS is required. The format of this statement is: 

DEFINE [READ] FILE #unit = filename, MIDAS [, record-size] 

The parameters used in the above format are explained below. 

Parameter Meaning 

#unit Ihe user-assigned unit number (either a literal or 

numeric expression); the # sign is required as in: 
#2. 

filename The name of the MIDAS file; must be enclosed in 

quotes, or must be a legal BASIC string expression. 

record-size The length of the MIDAS data subfile record in words ; 

(optional) if the MIDAS file has fixed-length records, this 
number, if specified, must match the data size 
indicated in the MIDAS file. (Use the PRINT option 
of CREATK to determine this. See Section 12.) No 
record-size is necessary if the file has 
variable-length records. (The default record-size is 
60 words.) 

The READ option opens the file for reading only; no records can be 
added to the file. The default access mode allows the full range of 
file operations to be performed on the MIDAS file (no restrictions) . 
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Table 8-1. Sutmary of A::cess Statements. 



kJUa i-^LLtCi I u 



AED 



DEFINE FILE 



P0SITIC»1 



Description 

Mds a record (by primary key) to the 
MIDAS file; secondary keys may be 
added also (optional) . 

Opens the designated MIDAS file on an 
available PRIMOS file unit and assigns 
a BASIC/W file unit ntmber to it for 
program reference. 

PDsitions the file pointer by key 
vali;e to a particular record in the 
file and locks it. 



READ 



REMOVE 



REWIND 



UPDATE 



Finds, locks and returns a MIDAS file 
record, by primary or secondary key; 
other options allow duplicate 

retrieval as well as sequential record 
retrieval. 

Deletes a record by primary key; 
also, can delete any secondary index 
entry. 

DDsitions the file pointer to the 
first entry in the specified index 
(defaults to primary index) . 

Itewrites the current record. 



All of these statements are explained in detail in the remainder of 
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Fbr example, the first of these two statonents opens a file with 
fixed-length records; the second opens a file vdth variable-length 
records : 

DEFINE FILE #1 = 'CUSTOMER' , MIDAS, 35 
DEFINE FILE #1 = 'SAMPLE' , MIDAS 



CLOSE Statanent 

MIDAS files are closed just like any other BASIC/VM file: 

CLOSE #unit 

The unit nimber is the user-assigned BASIC/VM file unit on vAiich 
the MIDAS file is opened. The # sign is required. 

Error Handling 

The BASIC/VM OJ ERROR statenent can trap MIDAS errors by directing 
program control to a statement which will be executed if an error 
occurs. CN ERROR traps only I/O errors on the particular unit on 
vhich the file v«s opened. A general error trap, as well as one 
for each file opened, may be in effect simultaneously. Ebllowing 
an error, the MIDAS code of this error can be obtained by using 
MIDASERR. This vorks much like ERR, the special error-code 
variable that returns BASIC/VM error codes. You can then look up 
the MIDAS error code in Appendix A to determine the nature of the 
problem. The ON ERROR format is: 

ON ERROR [#unit] GOTO line-nunber 

#unit is the user-assigned unit nun±>er on which the MIDAS file was 
opened. If #unit is not specified, all I/O errors occurring on 
every opened file unit will be trapped. 1 ine-nunber is the line 
nunber of the first statement of the error handler. 

lb print out the MIDAS error code, use the following PRINT 
statement : 

PRINT MIDASERR 



FILE POSITIONING 

Almost all of the BASIC/VM file handling statenents use and/or set 
the current file position. The current file position is considered 
that record in the file at which the file "pointer" is pointing. 
The file position is actually established according to an index 
subfile. This makes sense because the only way records can be 
retrieved from the data subfile is via pointers to the records in 
the index subfiles. Thus the "file pointer" actually points to a 
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specific entry in some index subfile, which contains a pointer to a 
record in the data subfile, making that record the current record. 

File position, then, can be established in the primary index 
subfile or in one of the secondary index subfiles. This can be 
done with the REWIND, POSITION or READ statements, all of vhich 
generally establish a new file position based on a user-specified 
key value. If the user does not supply a key value or an index 
number, the file position is set by default using the primary 
index. The "current record" would then be set to the record 
referenced by the first entry in the primary index subfile. It may 
be helpful to think of the index stfcfile v*iich is pointing to the 
current record as the "current index." 

Other BASIC/VM MIDAS access statements use the current file 
position to perform some action, and some of them reset it to a new 
location after the operation is complete. All of this is important 
only v*ien trying to visualize vhere you are in the file at any 
given time. "The idea of the "current record" and current file 
position will beccsne clearer as you familiarize yourself with the 
way these statements actually work. 



Locking/Lftilocking 

Tnere are no "lock/unlock" statanents in BASIC/VM; therefore, in 
order to preserve the integrity of any record, the READ, UPDATE, 
POSITION and DELETE statements all lock a record before they 
perform their respective operations. By locking the record, 
BASIC/VM protects the record from accidental harm by another user 
or process. It is a good idea to include error traps in your 
programs for records that may already be locked by another user 
vAien you try to access them. Specifically, one wDuld want to trap 
for a MIDAS error number 14. (See ^pendix A of this book for a 

1 T c-l- r\^ MTnZiC arv-fw rtr^f^cic \ 

The POSITION Statement 

The POSITIW statement moves the file pointer to any record in the 
MIDAS file, making it the current record. POSITION locks the 
record, leaving it locked until the file pointer is positioned to 
another record. 
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The format is: 



SEQ 



[,KEy [key-number] = key^value 
SAME KEY 



POSITICN #unit 
The parameters and keywords used in the format are explained below. 



Parameter 
key-^i umber 

key-value 
SEQ 

SAME KEY 



Meanirq 

Key nun±)er (index subfile number) , vAiich may be a 
literal or numeric expression; if unspecified or 
zero, it is taken as the primary key. 



Key value enclosed in quotes, or a 
expression. 



legal string 



Ftositions pointer to the next sequential record 
in the file according to the order of entries in 
the current index. 

The next record is made current if it has the 
same key value as the current record; used vitien 
most recent file position was established via a 
secondary key allowing duplicates. 

If there is no record at the file position specified, an error will 
be flagged. Some examples of the various POSITI(»J options are: 

POSITION #1, SME KEY 
POSITIOl #4, SEQ 
POSITION #2, KEY 3 = '478' 

few POSITION Vfcirks ; Records are positioned by primary or secondary 
key, as specified on the POSITICN statement line. This establishes 
that key as the "current key of reference" and it establishes the 
index subfile in which that key's value is stored, as the current 
"index of reference." If no key number is specified, the primary 
key is assumed, and POSITICW uses the primary index subfile as its 
index of reference. (Ihe primary key is then the "key of 
reference.") Once an index of reference is established, the file 
can be processed sequentially without explicitly referring to a key 
number or index subfile. All "read" requests are interpreted 
relative to that index; that is, records are read in the order in 
v\*iich their key values appear in the index of reference. (More on 
this under READING RECORDS.) 



REV. 



IDR4558 BASIC. VM INTERFACE 



The REWI^ro Statement 

Ihe REWIND statement '""sitions to and makes current the record with 
the lowest value for the specified key. If no key number is 
specified, the primary key is assumed. Essentially, REi^/IND just 
sets the file pointer relative to the first entry in the indicated 
index subfile. (Remember that references to key nunbers are really 
references to index subfile nunbers.) The REWIND statement format 
is: 

REWIND #unit [ , KEY nun-expr] 

num-expr is the key (index subfile) number; it must be used with 
KEY option. 

Examples : The first example sets the file position to the record 
referenced by the initial entry in the primary index. The second 
sets the position to the record referenced by the first entry in 
secondary index subfile 03. 

REWIND #3 
REWIND #2, KEY 3 



■The ADD statanent adds a record to a MIDAS file; it does not 
change the current file position or the current record. Although 
only the primary key value is required in an ADD, one or more 
secondary key values may be added to the appropriate index subfiles 
with a single ADD. In fact, this practice is recommended because 
it avoids the possibility of having index entries that don't match 
the key values in the data record. Whenever keys are being kept in 
the data record, it's important to make sure the entries in the 
primary and secondary index subfiles are the same as the key 
entries stored in the data subfile record; it minimizes confusion. 
The format of the ADD statement is: 

PRIMKEY 
ADD #unit, new-record, KEY[0-expr] = key0-val [,keylist] 

where keylist has the form: 

KEY key-number = key-val . . . 

Ihis expression can be repeated for each secondary key field in the 
record. The key values assigned here should match the key values 
in the data record ( new-record ) , if you are storing keys in the 
data record . Ihe paraneters are described below. 
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Parameter Explanation 

new-record Eeta record to be added; should be equal in 
length to the record size declared for the file, 
if the file has fixed-length records; record 
should be padded to correct length with blanks. 
If you want keys stored in the record, make sure 
new-record includes all the key values. 

PRIMKEY Both of these keywords represent the primary key. 

KEy[0-expr] 0-expr is a literal or nuneric expression that 
evaluates to zero. 

key0-^al Represents the primary key value : may be a string 

expression or a literal. 

keylist An optional list of secondary key numbers and 

values. 



key-nunber A numeric expression indicating 
nunber (index subfile nuniber) . 

key-val A string expression or literal 

secondary key value. 



a secondary key 



containing 



Chly the keys which are explicitly specified in the keylist are 
entered in the respective index subfiles. It is reccxnmended that 
you add all index entries at the sane time to avoid possible 
ambiguities. The example below shows an ADD statement that adds 
all the index entries along with the data subfile entry (also 
called the "data record") . 



AEP Eicample 

This example shows a BASIC/VM program v*iich adds records to the 
CUSTCMER file created in Section 2. This program reads data from a 
sequential disk file, called NAMES, pads each record with blanks 
until it's the proper length, then adds each record to the data 
subfile. At the same time, the primary and secondary key entries 
are placed in the proper index sttifiles, because all the necessary 
key values were included in the keylist. This example also shows 
the output from the program when it is executed. Notice that the 
program is run f ran PRIMOS command level , using the BASICV ccxnmand . 

OK, slist add .basic 

10 DEFINE FILE #1 = 'CUSTOMER', MIEftS, 35 

20 DEFINE FILE #2 = 'NAMES', 17 

30 DEF FNS$(X$,N) ! PADS STRING X$ WITH SPACES 

40 ! ADD SPACES UNTIL THE LENGTH EQUALS 70 CHARACTERS 

50 X$ = X$ +' ' UNTIL LEN(X$) = N 

60 FNS$ = X$ ! ASSIGN THE NEW PADISD STRING TO FUNCTION 

70 FNEND ! END OF PAD FUNCTION 

80 J = 7 
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90 N = 70 ! NIMBER OF CHARACTERS PER RECORD 

100 F(» I = 1 TO J 

110 READ #2,- A^ 

120 PRINT 'RECORD VALUE IS:': A$ 

130 B$ = SUB(A$,l/5) 

140 PRINT 'PRIMARY KEY IS:': B$ 

160 C$ = SUB(A$,6,30) 

170 D$ =SUB(A$,31,34) 

180 ! PAD STUFF HERE 

190 A$ = FNS$(A$,N) 

200 AID #1, A$, FRIMKEY = B$, KEYl = C$, KEY2 = D$ 

210 NEXT I 

220 CLOSE #1 

230 CLC^E #2 

240 PRINT 'DOJE' 

250 END 

OK, basicv add .basic 



RECORD VALUE IS: 2194G^ctrographics 
PRIMARY KEY IS: 2194G 
RECORD VALUE IS: 1002PFlora PDrtraits 
PRIMARY KEY IS: 1002P 

9411PStudio Wfest 
9411P 

9402AArtistry Ihltd. 
9402A 



RECORD VALUE IS: 
PRIMARY KEY IS: 
RECORD VALUE IS: 
PRIMARY KEY IS: 



REv^ORu VnliJE IS: 0816Sr'forrow I^pei. Mills 

PRIMARY KEY IS: 0816S 

RECORD VALUE IS: 2334PSeacoast Strippers 

PRIMARY KEY IS: 2334P 

RECORD VALUE IS: 4056SMark-Burton 

PRIMARY KEY IS: 4056S 

DONE 

OK, 



NWOR 
NENY 
WRCA 
WRCA 
NENH 
WRCA 
NEMA 



A Nate on Record Size 
the above 



Please note carefully the method used in 
pad the data record to the specified record 

or you'll 
If your 



example to 
length. This is mandatory in fixed-length record files 
get an error message when you attanpt to add the record, 
file has variable-length records, don't worry about this. 
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READING RECORDS 

The BftSIC/VM READ statement provides users with a complete range of 
options for getting information out of a MIDAS file. You can read 
a MIDAS file both randomly and sequentially, on any index, and you 
can alternate easily between the tWD types of reads. A READ 
operation always locks the record to v*iich it positions, guarding 
against concurrency errors. When the READ is complete, the record 
remains locked until another operation is performed to change the 
file pointer location. 



CVerview of READ Options 

With the SEQ option, the file can be processed sequentially on any 
index; this operation is equivalent to a "read next." The SAMEKEY 
option allows the retrieval of items with duplicate secondary key 
values. Partial key searches are permitted on any key; a special 
"READ KEY" option returns the full value of any key as stored in 
the appropriate index subfile. 

An optionless READ returns the current record, vrfiich is the record 
to v*iich the file pointer is currently positioned. 



The READ Statement Ebrmat 



The READ statement format allows you to read records from a MIDAS 
file sequentially, by duplicate keys and by primary or secondary 
key values. The format is: 



READ [KEY] #unit 



SEQ 
, [KEY [key-num] = key-val] 
SAMEKEY 



, read-var 



The keywords and parameters used in this format are: 
Parameter Explanation 



[KEY] 



#unit 



KEY 



Optional; for reading the full value of any key 
as contained in an index subfile. 

The user-assigned unit number on v^iich the file is 
opened; the # sign is required. 

Ihis keyword is used with key-num and key-val to 
indicate which record should Be rea^T IT the 
KEY [key-num] = key-^al clause is omitted, the 
current record is read. In this case, the current 
record must be established by a POSITION or REWIND 
statement . 
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key-num A literal or numeric expression indicating which 

key (index subfile) should be used in this 
retrieval. If omitted, the default is (the 
primary key) . 

key-val Ihe full or partial value (see below) of the key 

on viiich to conduct the search; if KEY [key-num] 
is used, a key-val must be supplied. 

SEQ Indicates that the next sequential record, as 

determined by current index of reference, should 
be read. 

SAMEKEY For reading duplicates; reads next record with 

the same key value as current record. 

read-var A string variable into v^iich the retrieved record 

value is read. 



READ Examples 

The following examples illustrate some uses of the READ statement 
as applied to MIDAS files; all are taken from BASIC/VM programs 
designed to access the CUSTOMER file created in Section 2 of this 

Sequential READs ; Ihe following program segment shows how to 
position the file by primary key and how to step through the file 
sequentially in primary key order: 



OK, slist readseq. basic 

10 DEFINE FILE #1 = 'CUSTOVIER', MIDAS, 35 

20 READ #1, G$ ! REA.DS FIRST ENTOY IN FILE 

30 PRINT G$ 

40 ! READ SEQUENTIALLY THRU FILE Oti PRIMARY INDEX 

50 PRINT 'STEP THRU FILE CN PRIMARY INDEX' 

60 PRINT 

70 N= 6 ! NO. RECORDS REMAINING IN FILE 

80 FOR I = 1 TO N 

90 READ #1, SEQ, G$ 

100 PRINT G$ 

110 NEXT I 
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The output from this portion of the program would be: 

OK, basicv read seq .basic 
0816SMDrrow I^per Mills NENH 

STEP THRU FILE ON PRIMARY INDEX 

1002PFlora Fbrtraits NENY 

2194GSpectrograp4iics NWCR 

2334PSeacoast Strippers WRCA 

4056SMark-Burton NEMA 

9402AArtistry iMtd. WRCA 

9411PStudio Wfest WRCA 



Similarly, if positioned by secondary key, vvhich can be done with 
either a POSITIC»J or READ statanent the file can be read 
sequentially in secondary key order, as shovai in the program 
excerpt below, v*iich is the second half of the program shown above: 



120 I STEP THRU FILE ON A SECC»JDARY INDEX 

130 PRINT 

140 PRINT 'STEP THRU FILE m SECOClARY INDEX 01' 

150 PRINT 

155 REM POSITION TO FIRST ENTOY IN INDEX SUBFILE 01 

160 REWIND #1, KEY01 

180 FOR I = 1 TO 6 

190 READ #1,SEQ,X$ ! READ NEXT 

200 PRINT X$ 

210 NEXT I 

220 CLOSE #1 

230 END 

The output from this portion of the program is: 

STEP THRU FILE ON SECONDARY INDEX 01 

1002PFlora Portraits NENY 

4056SMark-Burton NEMA 

0816SMorrow Paper Mills NENH 

2334PSeacoast Strippers WRCA 

2194G^ctrographics NWOR 

9411PStudio Wfest WRCA 



Random READs : lb randomly locate a particular file value, use the 
"KEY [key-nun] = key-val" option, as in: 

READ #1, KEY02 = 'WRCA' , G$ 

This READ returns the first record with the secondary key value 
'WRCA'. 



REV. 8-12 



im4558 BASIC/VM INTERFACE 



Finding Duplicates ; "lb find all the records with the same 
secondary key value, use the SAMEKEY option, as in: 

OK, slist dups .basic 

10 DEFINE FILE #1 = 'CUSTOMER' , MIDAS, 35 

20 ! THIS PROGRAM FINDS FIRST OCCURRENCE OF A CERTAIN 

30 ! SECONDARY KEY VALUE AND THEN FINDS ALL THE DUPLICATES 

40 READ #1,KEY02='WRCA', G$ 

50 roiNT ' FIRST RECORD WITH THIS VALUE: ' , G$ 

60 PRINT 

70 1 NOW READ ALL DUPLICATES OF THIS KEY 

80 ON ERROR GOTO 160 

90 1 ERROR WILL OCCUR WHEN NO MCKE KEYS ARE FOUND WITH THIS VAL 
UE 

100 PRINT 'RECC«DS WITH DUPLICATE VALUES ARE:' 

110 PRINT 

120 FC» I = 1 TO 5 

130 READ #1, SAMEKEY, S$ 

140 PRINT S$ 

150 NEXT I 

160 I ERROR HANDLER 

170 FRINT 'BASIC ERRO^ IS:', ERR$(ERR) 

180 CLOSE #1 

190 END 

OK, basicv dups .basic 

FIRST RECORD WITH THIS VALUE: 

9411PStudio Wfest WRCA 

RECORDS WITH DUPLICATE VALUES ARE: 

9402AArtistry IMltd. WRCA 

2334PSeacoast Strippers WRCA 

BASIC ERRCR IS: RECORD NOT FOUND 

Cbviously, this kind of program would only work v*ien secondary keys 
allow duplicates, as explained in Section 2. The duplicate feature 
is turned on or off during template creation. The error handler is 
used to trap the error that will inevitably occur v*ien we find no 
more duplicates for this key value. 

Reading on Partial Key Values : fertial key values can be used in 
any READ statanent, as in: 

READ #1, KEY 1 = 'Flor' , K$ 

The full value of this key is actually "Flora Partraits". Remember 
that only prefixes of a key value are allowed as partial key 
values. In other wrds, it WDuld not be legal to do a search on 
"Portraits" in this case. 

The READ KEY Option : The READ KEY option can be used to return 
the full value of any key. With it, you can find out v*iat key 
you're currently positioned on, (that is, vAiat index you're using 
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as the index of reference) ; alternatively, you can obtain the full 
key value of any key by specifying a partial value. Fbr example: 



OK, slist readkey.fc>asic 

10 DEFINE FILE #1 = 'CUSTOMER', MIEAS,35 

20 ! READ RECCM) WITH PARTIAL KEY 

30 READ #1, KEY 1 = 'Flor' , K$ 

40 PRim 'RECORD READ WITH PARTIAL KEY:' , K$ 

50 ! RETURN FULL VALUE OF CURRENT KEY OF REFERENCE 

60 READ KEY #1, H$ ! READS CURRENT KEY POS'D TO 

70 PRINT 'CURRENT KEY VALUE IS:' : H$ 

80 ! READ KEY CAN ALSO BE DONE WITH A KEY SEARCH CLAUSE: 

90 READ KEY #1, KEY2 = 'NE' , K$ 

100 ! FIND RECCM) WITH PARTIAL KEY VALUE 

110 ! THEN RETURN FULL KEY VALUE 

120 PRINT ! SPACE 

130 PRINT ' FULL KEY : ' : K$ ! KEY USED IN READING RECORD IS READ 

140 CLOSE #1 

150 END 

OK, basicv read key .basic 

RECORD READ WITH PARTIAL KEY: 

1002PFlora Partraits NENY 

CURRENT KEY VALUE IS: 

Flora Rartraits 

FULL KEY : 

NEMA 

OK, 



UPDATING RECORDS 

The UPDATE statement replaces the current record with a new record 
value. UPDATE does not change any of the index subfile entries so 
don't attempt to change key values with UPDATE. The proper way to 
change key values is to delete the record and then add it back 
again with the new key values. The UPDATE format is: 

UPDATE #unit, new-record 

#unit is the user-assigned file unit on v*iich the file is open. 
new-record is the new data record value; can be a string variable 
or a quoted literal. 
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Since an update operation is usually done to modify a certain 
record, the record should first be read to establish it as the 
current record, and to return the contents of that record to be 
modified. It is not necessary to do a READ to establish the 
current record position, as a REWIND or POSITION statement can be 
used to the same purpose. The user should note that UPDATE 
overwrites the existing record — it does not delete and replace 
it. lake care to make the new record equal in length to the old 
one so that all the old data is completely overwritten. 

For example: 

OK, slist update .basic 

10 DEFINE FILE #1 = 'CUSTOMER', MIDAS, 35 

20 ! FIND RECORD TO BE UPDATED 

30 READ #1, KEY1='SEA', X$ 

40 PRINT 'ORIGINAL RECORD IS:', X$ 

50 PRINT 

60 ! UPDATE THIS RECORD BY ADDING SOMETHING TO THE END 

70 A$= 'Contact Marvin' 

80 ! WRITE THE ORIGINAL RECORD BACK WITH THIS ADDITIC»J 

90 X$ = SUB(X$,1,35) ! TAKE JUST THE NON-BLANK PART 

100 X$ = X$+A$ ! COMBINE THE WO 

110 1 NOW PAD TO COy^ECT LENGTH 

120 X$ = X$ +' ' UNTIL LEN(X$) = 70 

130 UPDATE #1,X$ 

140 REWIND #1 

150 READ #1, KEY='2334', X$ 

160 PRINT ' UPDATED RECORD: ' , X$ 

170 CLOSE #1 

180 END 

OK, basicv update .basic 

ORIGINAL RECORD IS: 

2334PSeacoast Strippers WRCA 

UPDATED RECORD: 

2334PSeacoast Strippers WRCA Contact Marvin 



In files with fixed-length records, be sure to pad the record to 
the correct length or you'll get a record-size error and the update 
will not occur. 



DELETING RECORDS 

The REMOVE statement selectively deletes index entries for a 
particular data record. If the primary key is specified, then the 
associated data record, as well as the primary index entries, will 
be deleted. In this case, the secondary key entries will not be 
deleted until they are used to reference the now deleted data 
record, or until MPACK is run on the file. (See Section 12.) 
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The REMOVE format is: 

REMOVE #unit [,KEY [key-nun] = key-val] [,KEY [key-nun] =key-val] .. . 

keyHiun is a nuneric variable containing an optional key (index 
subfile) nunber. This is the key to be deleted. If a key nunber 
is not specified, the primary key is assuned. MDre than one key 
value can be deleted in a single REMOVE statement, as shown in the 
above format. key-val is a string expression containing a key 
value; along with key-nun , it indicates vhich primary or secondary 
key entry is to be removed from an index subfile. lb delete the 
current record, use the optionless form of REMOVE. 

Example 

The following example shows how specific secondary key values can 
be removed frcxn an index, and how an entire record and its primary 
index entry can be deleted. In addition, it uses the MIEASERR 
feature to print out the MIEftS error code associated with the read 
error that will occur on an attempt to read a deleted record. 

OK, slist delete .basic 

10 DEFINE FILE #1 = ' CUSTOMER', MICAS, 35 

20 ! REMOVE A SECOyJDARY INDEX ENTRY FRCM TOIS FILE 

30 miNT 'REMOVE THE SBCONEARY KEY VALUE: Studio Vfest' 

40 REMOVE #1, KEY01=' Studio West' 

50 ! BUT THE RECORD VALUE REMAINS UNCHANGED 

60 PRINT 

70 READ #1, KEY = '9411P', X$ 

80 reiNT 'RECORD VALUE IS:' :X$ 

90 REWIND #1, KEY01 ! POSITION TO TOP OF SEC(M)ARY INDEX 01 

100 ! READ FILE ON SECONDARY KEY 

110 ! 

120 ON ERROR GOTO 210 

130 PRINT 

140 PRINT ' RECORDS READ BY SECONDARY KEY: ' 

150 PRINT 

160 FOR I = 1 TO 6 

170 READ #1,SEQ,N$ 

180 PRINT N$ 

190 NEXT I 

200 ! DELETE THE RECORD 

210 PRINT 

220 PRINT 'NOTE: RECORD REFERENCED BY DELETED ' 

230 PRINT • INDEX ENTRY IS NOT PRINTED' 

240 PRINT 

250 PRINT ' DELETE RECORD BY PRIMARY KEY' 

260 REMOVE #1, KEY0='9411P' 

270 REWIND #1 

280 ! 

290 ON ERROR GOTO 340 

300 PRINT 

310 READ #1, KEY='9411', X$ 
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320 PRINT X$ 

330 GOTO 360 ! IF NO ERROR 

340 PRINT 'MIDAS ERROR CODE:' : MID^EPJl 

350 PRINT 'BASIC EBROR IS:': ERR$(ERR) 

360 CLOSE #1 

370 END 

OK, basicv delete .basic 

REMOVE THE SECONDARY KEY VALUE: Studio Wfest 

RECORD VALUE IS: 

941lPStudio Vfest WRCA 

RECORDS READ BY SECONDARY KEY: 

1002PFlora PDrtraits NENY 

4056SMark-Burton NENA 

0816SMorrow Paper Mills NENH 

2334PSeacoast Strippers WRCA 

2194GSpectrog rallies NWCB 

NOTE: RECORD REFERENCED BY IXLETED 
INDEX ENTRY IS NOT PRINTED 

EELETE RECORD BY PRIMARY KEY 

MIDAS EPROR COISl: 7 

BASIC ERROR IS: RECORD NOT FOUND 

OK, 

The MIDAS error code of 7 indicates an unsuccessful read resulting 
from a failure to find a record with the indicated key value. You 
can verify this by looking up MIDAS error 7 in appendix A. 
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INTRODUCTION 

This section documents the PI/I subset G interface to MIDAS files as 
implonented at this revision of MIDAS (17.6) . The term Pt/I as it is 
used in this section refers exclusively to Prime's Subset G version of 
the PI/I language unless otherwise indicated. 

From PI/I's point of view, a MIDAS file is simply a RECORD KEYED 
SEQUENTIAL file that can be accessed by the standard PI/I READ, WRITE, 
REWRITE and DELETE statements. HDwever, the MIDAS file must have an 
ASCII primary key: this is a PI/I requirement. In addition to 
supporting CREATK-de fined files, PI/I can create its own MIDAS files. 
A Pl/I-created file has an ASCII primary key of 32 characters in length 
and variable-length records. Further restrictions on the PI/I 
interface are discussed later. 

In this section, the syntax and usage of PI/I statements are addressed 
in relation to MIDAS only; consult The PI/I Subset G Reference Guide 
for complete syntax information on these and other PI/ I statanents 
referenceu nere. 



language Limitations 

The PI/I Subset G interface to MIDAS does not support the following 
MIDAS features: 

• non-ASCII primary keys 

• Secondary keys 

• Direct access MIDAS files 

• Secondary data 

Because PI/I does not support secondary keys or non-ASCII primary keys 
you can't use PI/I to set up a MIDAS file template with these features. 
To create a MIDAS file with secondary keys, fixed-length records or a 
primary key of less than 32 characters, use CREATK instead. You can 
access such a file frcxn a PI/I program as long as its primary key is a 
character string of 32 characters or less. Existing MIDAS files with 
secondary keys can still be accessed from a Pt/I progran, but you will 
not be able to access any secondary index subfiles from PI/ 1. 
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Note on Cbnversion 

Ihe restriction on primary key type applies only to the actual 
definition of the primary key during tenplate creation. As long as the 
primary key is declared as an ASCII character string of 32 or fewer 
characters, the file can be accessed from PI/I using character or 
nuneric key values. Mmeric values will be converted to character 
strings in accordance with standard PI/I conversion rules. 

Running a PI/I Program 

You don't need to load any special libraries in order to run a PI/I 
program that accesses MIDAS files. Just follow this sample compile and 
load sequence. User input is underlined to distinguish it fran syston 
output. 

OK, pllg program 

0000 ERRORS (PLIG-REV 17.6) 

OK, seg^ 

[SEG rev 17.6] 

# lo #program 

$ lo b-program 

$ li plllib 

$ li 

LOAD CCMPLETE 

$ sa 

$ q 

OK, seg #program 

Substitute the name of your program for the program argument in the 
above example. 



OPENING/CREATING A MIEAS FILE 

There are tWD ways to create a MIDAS file for use with PL/I: you can 
create the file with CREATK, and then simply open it for reading and/or 
writing frcm a PI/I program; or, you can create a MIDAS file fran PI/I 
using the standard file I/O statements. The next part of this section 
tells how to open an existing MIDAS file and how to create a new one 
with PI/I. 



Creating a MIDAS File from PL/I 

When creating a MIDAS file fran a PI/I program the file must be 
explicitly declared with the KEYED SEQUENTIAL [RECORD] attributes. 
Iheir order doesn't matter. The RECORD attribute is implied by the 
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KEYED attribute and need not be specified. Follow this simple sequence 
in creating a MIDAS file from PI/I: 

DECLARE filename FILE KEYED SEQUENTIAL; 
OPEN FILE(filename) OUTPUT; 

The FILE keyword in the DECLARE statement can appear before or after 
the actual filename . The DECLARE statonent can be abbreviated to DCL. 
These statonents tell MIDAS to open a MIDAS file with the default 
attributes mentioned above. (See The PI/ 1 Subset G Reference Guide for 
details on OPEN and DECLARE syntax and attributes.) THe MIDAS file 
will have variable-length records with a maximum length of 2048K words 
(4096 bytes) and a primary key of 32 characters in length. 

Althoi^h the default primary key is defined as an ASCII character 
string, PL/I conversion rules permit you to then define the primary key 
from program level as a character or numeric item. Thus you can write 
file entries with character or nuneric key values. Keep in mind that 
the data must be read out in the same format as it was written. You 
can't mix and match data types in WRITES and REAEB. 



Opening an Existing MIDAS File 

Tb open an existing MIDAS file that was previously created with PI/I/ 
use the OPEN statement with this format: 



OPEN FILE (filename) 



INPUT 

OUTPUT 

UPDATE 



filename must be no longer than 8 characters in length, and may be 
specified before or after the FILE option. The file should first be 
declared as KEYED SEQUENTIAL. The INPUT, OUTPUT and UPDATE options 
iixJicate the access mode in viiich the file should be opened. The 
access mode controls the types of operations vvhich can be performed on 
the file. 

The INPUT option ; allows READ operations only. It defines the access 
mode for this file as "read only". 

The OUTPUT option : permits only write operations and is primarily used 
to open and create new files. It also allows additions to be made to 
an existing KEYED SEQUENTIAL file with the indicated name; however, if 
no such file exists, PI/I creates a new one. Neither read nor update 
operations cannot be performed on a file opened for OUTPUT. 

The UPDATE option ; permits READ, WRITE, UPDATE and DELETE operations 
on an existing file. Use UPDATE when making changes or additions to an 
existing file. 
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Combining DCL and 0PE3SI ; Alternatively, the INPUT, OUTPUT or UPDATE 
options can bi included in the DECLARE statement V\*iere the KEYED 
SEQUENTIAL file is first declared, eliminating the need for an explicit 
OPEN statement: 

DECLARE SAMPLE FILE KEYED SEQUENTIAL OUTPUT; 

or 

DCL OTHER FILE KEYED SEQUENTIAL INPUT; 

Remonber that a file opened or declared as INPUT or UPDATE must already 
exist — if it doesn't, an error is signalled. 

Note 

For information on opening non-PL/ I-created files, (i.e., MIDAS 
files created directly with CREATK or KX$CRE) , see Opening 
CREATK-de fined Files at the end of this section. 



FILE I/O CONCEPTS IN PI/I 

The ranainder of this section deals with these PI/I statenents, v^ich 
are all used to access MIDAS files from PL/I programs: 

PL/ 1 Statanent Function 

READ [KEY] Reads next sequential record in file (if 

KEY not specified) or reads record with 
the indicated KEY value. 

WRITE Pdds a new record to the bottom of the 

file with a specified primary KEY value. 

REWRITE [KEY] Updates (rewrites) the indicated record 

(KEY specified) or the current record (no 
KEY). 

DELETE [KEY] Deletes the specified record (KEY 

specified) or the current record (no 
KEY) . 

Ihe access mode for which the file is opened restricts the use of these 
statements . 
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Ihe table below indicates vAiich stat^nents can be used in each access 
mode: 

INPUT OUTPUT UPDATE 



READ WRITE READ 

WRITE 
REWRITE 
DELETE 

The topics addressed in the ranainder of this section are: 

• The current record in PI/I file I/O 

• Vft-iting to a file (new or existing) 

• Data size/ record length 

• Reading a file (sequentially or by key) 

• L^ating file records 

• Deleting file records 

• Locked records 

• Accessing CREATK-defined files 



The Current Record in PL/I 

In PL/I the current file position is handled automatically so you don't 
have to vorry about a communications array to keep track of the current 
record (as in the FORTRAN interface) . PL/I's READ statanent advances 

file before performing the read operation. After a READ, the current 
record is always the one just read. The WRITE statement positions to 
the proper spot in the primary index subfile so it can insert the 
primary key value of the record being added in its proper place. Thus 
the current record after a WRITE is the record just written. When a 
DELETE is performed, the current record position is not moved, but is 
instead left undefined. That is, no record is "current" after a DELETE 
because DELETE always ronoves the current record. REWRITE does not 
update the current record position at all. 

Initial "Current" Record ; When a MIDAS file is opened for INPUT or 
UPDATE in PL/I, the current file pointer is set just prior to the first 
record in the file; a current record position is established by a READ 
(with or without KEY) , or any other I/O operation permitted by the 
access mode. This establishes the current file position and 
initializes the MIDAS communications array V\iiich PL/I handles 
(transparently) for the user. (This means you don't have to worry 
about itl) . 
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DELETE and the Oirrent Record : After a DELETE operation, the current 
record is left undefined until the next READ or WRITE operation. A 
sequential READ (without the KEY option) will work unless you just 
deleted the last record in the file. A WRITE operation positions the 
file pointer to the place in the index v*iere the key entry associated 
with the record to be written logically fits according to the collating 
sequence . 



AIDING RECORDS 

lb add records to a new or existing file, the file must first be opened 
for OUTPUT or UPDATE. Records are then written to the MIDAS file with 
a PI/ I WRITE statement: 

WRITE FILE (filename) FROM(var) KEYFRCM(keyvar) ; 

The var argunent contains the new record information. Its data type 
should be declared as CHARACTER; its size, which PL/I views as the 
record size, can be declared varying (VAR) if desired. (See Declaring 
Data Size below.) 



The KEYFRCM Cption 

The KEYFRCM option specifies the primary key value for this new record; 
KEYFROM and a unique key value must be present in every WRITE statement 
performed on a MIDAS file. keyvar can be declared as a character 
string of 32 characters or less, or as a numeric field ,for example, 
fixed bin, fixed decimal, and so forth. If declared as a CHARACTER, it 
cannot be declared as VARYING. Furthermore, if the template was 
created with CREATK, the variable should match in size and type the 
primary key as defined during template creation. 

Inside Story ; PL/I always writes 32 characters per index entry, 
regardless of how many non-blank characters you specify in a WRITE 
statonent and regardless of how you define the primary key in yaur 
program. It may be wise to declare the key variable as 32 characters 
even if you only have a 6 character key, for example. It's better to 
have PL/I add the remaining 26 characters as blanks than to have 
unpredictable "garbage" values stored in the index entry slot. 

Up Duplicates Allowed ; The key value specified for keyvar must not 
already exist in the file or a KEY error will be reported, causing 
program execution to halt. Remember, primary keys must be unique in a 
MIDAS file — you must supply a new value for the keyvar argument with 
every WRITE statanent. (For more details on KEY errors, see Error 
Handling, below.) 
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The WRITE Operation 

WRITE updates the current record position in order to add a new record 
to the file. It doesn't matter vAiich record is current prior to a 
WRITE operation, because WRITE takes care of positioning the file to 
the proper index location. The current record after a WRITE is the one 
just written, so a "read next record" operation subsequent to a WRITE 
returns the record immediately following the one just added. However, 
the file must be opened for I/O or OUTPUT in order to add records to 
it. Each WRITE operation places key entries in their proper slots in 
the index the program-supplied primary key entry into its proper slot 
in the index and adds the corresponding data record to the bottcm of 
the data subfile. Keys are added to the primary index subfile in 
ascending order by key value regardless of the fact that data subfile 
records are written to the bottom of the data subfile. This means that 
when reading sequentially through the file, you'll get all the records 
in the order you expect (based on primary index entry order) rather 
than in the order in v*iich you added them — unless, of course, you 
added them in ascending key order in the first place! 

Declaring Data Size 

It is not possible to create a true fixed-length record MIDAS file from 
a PE/I program. HDwever, you must declare a maximum size for the data 
variable from v*iich each MIDAS file record will be written. This is 
the variable into vAiich the user's program puts data record information 
so it can be written to the MIDAS file as a unit. By setting the size 
of this variable, you effectively limit the record size of the MIDAS 
file: 

DECLARE SAMPLE FILE KEYED SEQUENTIAL; 

DECLARE PKEY CHAR (32) ; 

DECLARE DATAVAR CHAR (30) ; 

PKEY = 'aaaa'; 

WRITE FILE (SAMPLE) FROM(DATAVAR) KEYFRC]M(PKEY) ; 

In this example, datavar is set at 30 characters, indicating that the 
records written to the MIDAS file SAMPLE will be 30 characters in 
length, datavar could be declared as "CHAR(30) VAR" to eliminate blank 
padding. PKEY represents the primary key field for each file record 
and is set to the default length of 32 characters. It doesn't have to 
be 32 characters long ~ this is the simply the maximum key size 
allowed by PL/ 1. 

Ebr Example : The OPENIT program, listed below, opens a new MIDAS file 
called SAMPLE and adds records to it. Primary key values are supplied 
in ASCII form because pkey is declared as char (32). If we wanted to, 
we could have declared the primary key as a fixed decimal nimber and 
then supplied the primary key values in numeric form. 



October 1980 



SECTION 9 IDR4558 



openit: 

proc options (main) ; 

/* This program creates a MIDAS file called Sample */ 

del sample file keyed sequential; /* MIDAS */ 

del pkey char (32); /* primary key */ 

/* recvar contains the data to add to the file */ 

del recvar char (30) var; /* record size */ 

open file (sample) output; /* for new file */ 

/* Values for pkey and recvar */ 

pkey = • 0001 ' ; 

recvar = 'first file record'; 

write file (sample) from(recvar) keyfrcm(pkey) ; 

pkey = '0002'; 

recvar = 'second file record"; 

write file (sample) from (recvar) keyf rom (pkey) ; 

pkey = '0003'; 

recvar = 'third file record'; 

write file(sample) from (recvar) keyf rom (pkey) ; 

close file (sample) ; 

end; 



Storing Primary Keys in Record 

To maintain data integrity and to allow for future file requirements, 
it might be a good idea to include the primary key in the data record 
proper. This can be done easily as shown in this example: 

add: 

proc options (main) ; 

/* this program adds a new record to the Sample file */ 

del sample file keyed sequential; 

del pkey char (32); /* primary key */ 

del recvar char (30) var; 

open file (sample) output; 

/* output mode is ok for adding records only */ 

/* primary key is in data record */ 

recvar = '0005fifth file record'; 

pkey = substr (recvar, 1, 4); 

write file (sample) from(recvar) keyfrom(pkey) ; 

close file (sample); 

end; 
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When reading the file, remember to use "PUT EDIT" to print out just the 
part of the record you want. The key can also be stored at the end of 
the data record- Avoid making changes to the "ke" field" of the record 
during an UPDATE because the primary key entry in the index subfile 
cannot be changed. 



READING A MIDAS FILE 

Ihere are three types of "file reads" that can be done on a MIDAS file 
from PI/ 1: 

• Keyed read - a record is found based on a user-supplied key 
value 

• Sequential read - (also called "non-keyed" read) records can be 
read from the file in primary key order; file position is 
established at some point in the primary index subfile, either 
by a keyed read or by default, which puts the file pointer at 
the beginning of the index subfile. 



• 



Reading keys - the full key value of the primary key, as MIDAS 
stores it in the primary index, is returned (can only be done in 
a non-keyed read) 



The READ Statanent 

The READ statement, with or without the KEY or KEYTO options, copies 
the contents ot one file record into a previously defined variable. 
Reminder : a file must be opened for INPUT or UPDATE in order to be 
read. "Ihe READ statonent format is: 

READ FILE (filename) INTO(var) [KEY(keyvar) ] [KEYTO(curkey) ] ; 

Ihe KEY and KEYTO Options 

The KEY (keyvar) option finds the record whose key matches the one 
specified by keyvar . KEY is used in keyed reads only (see Keyed feads 
below); if omitted, the next sequential record is read. The keyvar 
argument should match the data type and size of the primary key as 
defined in the program that wrote entries to the file. Ebr example, if 
you wrote records using a primary key declared as FIXED(4) , you should 
read the file with the primary key declared as FIXED(4) . 

The KEYTO option copies the key value for the current record into the 
cur key argunent. (The key value is read from the primary index 
subfile.) The cur key argument must always be declared as CHAR(32) 
VARYING, because of the way in vrfiich PI/I handles the MIDAS index 
subfile entries. 
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Note 



The KEY and KEYTO options cannot appear together in the same 
READ statanent. KEY is generally used for keyed reads v*ien the 
key value of a record is known; KEYTO, on the other hand, is 
used during sequential reads v^en you want to determine the 
primary key value of the current record. KEYTO is especially 
useful v*iere keys are not stored in the actual data file 
record . 



The "Read" Variable 

The record is reaa into the var variable, v*iich must be declared 
according to the following rules: 

• For PL/I-created files, var must match in size and type the 
WRITE argument v*iich was used in writing this record. Fbr 
example, the recvar argunent, as used in: 

WRITE FILE(filenane) FROM(recvar) KEYFRCM(pkey) ; 

must match the var argument as used in the above format. 

• For non-PI/I-created MIDAS files with fixed-length records, 
simply use the fixed record size value in declaring the INTO 
argunent. See Reading Fixed-Length Records , below. 

• For variable-length records in a file not created by PL/I, see 
Fteading Variable-Length Records later in this section. 

feyed Reads 

Keyed reads are performed by specifying a valid key value with the KEY 
option. "Valid" means that the value must occur in the primary index 
subfile of the MIDAS file being read . Key values that do not appear in 
the MIDAS file cause KEY errors and program halts. If a match is 
found, this record becomes the current record, and the contents of the 
record are placed in the specified read variable. For example: 

DECLARE SAMPLE FILE KEYED SEQUENTIAL; 

DECLARE PKEY CHAR(32) ; 

DECLARE READVAR CHAR(30) ; 

PKEY = 'aaaa' ; 

READ FILE(SAMPLE) INTO(READVAR) KEY(PKEY) ; 

PUT LIST (READVAR) ; 



Sequential Reads 

A MIDAS file can be read sequentially, in primary key order, by using 
READ without the KEY option. The current record pointer simply 
advances to the next record in the file every time a READ operation is 
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performed. An error occurs if the pointer is at the bottan of the file 
because there are no more records to be read. fin exanple of a 
sequential read might be: 

ON ENDFILE( SAMPLE) GOTO CIjOSE_FILES; 
DO WHILE('l'B) ; /* infinite loop */ 
READ FILE(SAMPLE) INTO(READVAR) ; 
PUT SKIP LIST(READVAR) ; 
END; 

All the records in the file frcxn the current record on vdll be read as 

the program loops; then the ENDFILE condition will be signalled and 

control sent to the part of the program labelled " CLOSE_FILES" where 
the file is closed. 



Reading Key Values 

The KEYTO option can be used to obtain the value of the primary key of 
the record currently being read: 

DECLARE KVAR CHAR(32) VAR; 

READ FILE (SAMPLE) INTO(READVAR) KEYTO ( KVAR) ; 

PUT SKIP LISTCRECCRD:', READVAR) ; 

PUT SKIP EDITCKEY VALUE:', KVAR) (A, X(2) , A(4)); 

The "PUT EDIT" statement is useful v*ien you vrant PI/I to print only the 
first few characters of the primary index subfile entry. Otherwise, 
PI/I prints a 32-character version of the primary key v*iich in this 
case consists of the four characters originally passed to MIDAS plus 28 
blanks . 

Sample Read Program : Below is a listing of a sample program v*iich 
performs keyed and sequential reads on the file created by the OPENIT 

T\ir r^t/^ V Sim T "1 c*~Oij^ S3»*"T ^ S** aT ^Ni-w-f T.T1 4-1-1 -l-V^o j-xii4-rMi4- -Pirj^m ■^V*s r\ir t'^/-^ ir ssm • 

^1. \J^ I. Cull j.xou.cfu cui.j.j.^1. f a.j.\jiM Vvj. L^ii i*iic ^^^.^^^i^u j-i.>b/iLi ^ii€ ^lvJ^^lCuii* 

read : 

proc options (main) ; 
del sample file keyed sequential; 

del pkey char (32) ; /* primary key */ 

del readvar char (30) var; 
/* make it the same as recvar */ 
del kvar char (32) var; /* reads keys */ 

/* KVAR is used with KEYTO option and must be CHAR VARYING */ 

/* set up an on-unit to handle end of file */ 

on end file (sample) begin; 

close file (sample) ; 

put skip listCEnd of file'); 

stop; 

end; 
open file (sample) input; 
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/* read with a key */ 

/* Note: the first READ doesn't have to be a keyed one */ 

pkey = '0001' ; 

read file (sample) into(readvar) key(pkey) ; 

put skip list{readvar) ; 

/* now read sequentially (without key) */ 

read file(sample) into(readvar) ; 
put skip list(readvar) ; 

/* read with KEYTO option */ 

/* now read next record and return the key value with KEYTO 
option */ 

read file(sample) into(readvar) keyto(kvar) ; 

put skip list(readvar) ; 

put skip editC Key value:' , kvar) (a, x(2) , a(4)); 

close file (sample) ; 

end; 
/* now run the program */ 
OK, seg #read 

first file record 
second file record 
third file record 
Key value: 0003 
OK, 



UPDATING FILE RECORDS 

Record updates in PI/I are performed with the REWRITE statement, which 
replaces either the current record (that is, the one just read) or the 
specified record with a new record value. 



The REWRITE Statement 

Records in an existing MIDAS file can be updated with the REWRITE 
statement : 

REWRITE FILE (filename) FROM(datavar) [KEY(keyvar) ] ; 

datavar is the variable containing the data v*iich will replace the 
record being updated. You can't update just part of a record — you 
must rewrite the v*iole thing. Bear in mind that keys cannot be changed 
— so if you've made an error vrfiile adding the original key field, 
delete the record and then WRITE it over the way you want it. 
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Sample Update Program ; This program performs an update on the MIDAS 
file Sample. Ihe output from the program is also included: 

update : 

proc options (main) ; 
del sample file keyed sequential; 

del pkey char (32) ; /* primary key */ 

del readvar char (30) var; 
/* make it same as recvar */ 
del kvar char (32) var; /* reads keys */ 

/* KVAR is used with KEYTO option and must be CHAR VARYING */ 

/* set up an on-unit to handle end of file */ 

on endfile (sample) begin; 

close file (sample) ; 

put skip list('End of file') ; 

stop; 

end; 
open file (sample) update; 
pkey = '0002' ; 

read file(sample) into(readvar) key(pkey) ; 
put skip list (readvar) ; 

/* update this record */ 

readvar = ' New second record ' ; 

/* use the KEY option to be sure */ 

rewrite file(sample) from(readvar) key(pkey) ; 

read file (sample) into (readvar) key(pkey) ; 

put skip list('Ifew record:' , readvar) ; 

close file (sample) ; 

end; 
/* now run the program */ 
OK, seg #update 

second file record 

New record : Nsw second record 

OK, 

REWRITE' s KEY Option 

The KEY option is used vAien you want to specify exactly vi^iich record is 
to be updated. Without the KEY option, REWRITE updates the current 
record, v*iich is the record just read by the last READ statanent, or 
the one just written by the last WRITE statement. This means that a 
current record position must have already been established (by a READ, 
WRITE or another REWRITE, this one with the KEY option) prior to a 
REWRITE without the KEY option. In this case, the MIDAS communication 
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array is used by PI/I to determine v*iere the current record is and 
which record should be updated. Ibwever, it is not necessary to 
perform either a READ or WRITE prior to REWRITE if the KEY option is 
used with REWRITE. 

In any event, it's good practice to use the KEY option to avoid 

confusion about which record is being updated. If the key value 

indicated by keyvar does not exist in the file, a KEY error is 
triggered and the program aborts. 



What REWRITE Ppes 

REWRITE uses either the communications array value or the supplied key 
value to determine vhich record is "current" . The current record is 
automatically locked during a REWRITE and kept locked until another I/O 
operation is performed. In other words, the current record position is 
not updated after the REWRITE operation is ccanplete. 



DELETING RECORDS 

Records are deleted from a MIDAS file by primary key; the index 
subfile entry is marked for deletion and the corresponding primary 
index value is deleted. 



The DELETE Statenent 

*Ib delete a record from a MIDAS file, use the DELETE statement. DELETE 
may be used with a KEY option to indicate vhich record is to be 
deleted : 

DELETE FILE (filename) [ KEY( keyvar) ] ; 

If specified, keyvar must be a key value that occurs in the MIDAS file, 
otherwise a KEY error occurs. If no KEY is specified, the current 
record is deleted. (It is assumed that the previous READ or REWRITE 
statement established the current record position.) DELETE does not 
update the file pointer location — thus, the current record is always 
left undefined. 

Ebr example, this program excerpt deletes a record from the Sample 
file: 

delete : 

proc options (main) ; 
del sample file keyed sequential; /* existing file 

*/ 

del pkey char (32) ; /* primary key */ 

del recvar char (30) var; 

del readvar char (30) var; 

del kvar char (32) var; /* reads keys */ 
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On page 9-15, the second and third <xininent lines from the top of 
the page should be omitted. This program contains no on-units for 
the KEY condition (using an invalid key in a file access 
operation) . This is why the error messages shown in the oitput 
occur. To help clarify this, the following s&nt&nce should be 
added before Reminders, on page 9-15: 

"Ihe error oonditiais are raised because there is no on-unit to 
tr^ KEY errors: see ERROR HfiNDLINa below." 
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/* KVAR is used with KEYTO option and must be CHAR VARYING */ 
/* spi- li p nn -n n1t i -i°r 1 i H i K l 1f" fll^ rt^frl '^rrmr'^ *•' ■ 



__/*-s et up an on unit to l ic niille fehd ot tile */ 

open file (sample) update; 
/* UPDATE mode required for rewrites or deletes */ 
pkey = '0002'; 

read file (sample) into(readvar) key ( pkey) ; 
put skip list(readvar) ; 

/* delete this record */ 

delete file (sample) ; 

/* check to see if this record is gone */ 

/* if it is, a KEY error will be raised */ 

read file(sample) into(readvar) key('0002'); 
close file (sample) ; 
end; 
/* now run the program */ 

nif Qp/-i #/^q1 ai-a 

New second record 

KEY( SAMPLE) raised in DELETE at 4001(3)/1211 

(record not found in READ) 

ERROR (file = SAMPLE) raised in DELETE at 4001(3)/1211 

(no on-unit for KEY) 

ER! 

Reminders ; A file must be opened for UPDATE in order to delete records 
from it. A READ or WRITE operation performed immediately after a 
DELETE works fine; however, a DELETE (with or without a KEY) or a 
REWRITE operation subsequent to a DELETE will signal an error. 

LOCKED RECORDS 

Because the PL/I READ and REWRITE statements always lock the current 
record, there are no specific lock/unlock statements in PI/I. The lack 
of such statements can cause some problems if the user hits CTRL-P or 
BREAK iitmediately after a READ or REWRITE operation. Frequently, the 
current record will ranain locked, since READ autcsnatically sets and 
locks the current record even though it never updates the current file 
position. When this happens, run the MPACK utility to unlock this 
record. MPACK is documented in Section 12. 
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ACCESSING CREATK-DEFINED FILES 



MIDAS files that are not created through PI/I can still be accessed 
from PE/I programs. Itowever, keep in mind the restrictions on READ and 
WRITE argument size. It's easier to determine how the arguments should 
be declared if the file in question has fixed-length records. 

Caution 

It may be a good idea to avoid updating the same MIDAS file 
with more than one high-level language interface, as this 
practice can result in file anomalies. 



Reading Fixed-Length Records 

When opening an existing CREATK-de fined MIDAS file with fixed-length 
records, determine the record size so you can use it in defining the 
READ or WRITE statement argunents. Use CREATK's PRINT function and 
enter "data" in response to the "INDEX NO?" prompt (See Section 12.) 

Ihe data size in wards is displayed next to "ENTRY SIZE". (Since PI/I 
cannot create a MIDAS file with fixed-length records, the ENTRY SIZE is 
displayed as "USER-SUPPLIED" for Pl/I-created MIDAS files.) Ebr 
example, the CUSTOMER file, created in Section 2, has fixed-length 
records of 35 words. It can be opened and accessed as shown in this 
PL/I program excerpt: 

DCL FILE CUSTOMERS KEYED SE(3UENTIAL; 

OPEN FILE CUSTOMERS INPUT; /* could open it for UPDATE also */ 

DCL READVAR CHAR(70) ; /* variable into v*iich record is read */ 

DCL PKEY CHAR (5); 

PKEY = '0212G'; 

READ FILE (CUSTOMERS) INTO(READVAR) KEY(PKEY) ; 

Since the record size is already known, the readvar variable is set at 
70 characters. Similarly, the primary key, defined here as pkey , was 
declared as 5 characters v*ien the file was created with CREATK. 

Sample Program ; This program, fran viiich the previous excerpt was 
taken, opens and reads the sample MIDAS file CUSTOMER, vAiich is a 
CREATK-defined file: 

custread : 

proc options (main) ; 

/* this program opens and reads from */ 

/* a previously-created MIDAS file CUSTOMER */ 

/* v*iich has fixed-length records */ 

del customer file keyed sequential ; 
del pkey char (5) ; 
del readvar char (70) ; 
/* reads keys */ 
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/* KVAR is used with KEYTO option and must be CHAR VARYING */ 
/* set up an on-unit to handle end of file */ 

on endfile(custc«ner) begin; 

close file (customer) ; 

put skip list('End of file'); 

stop; 

erd; 
open file (customer) input; 
pkey = ' 2194G' ; 

read file (customer) into ( readvar) key (pkey) ; 
put skip list (readvar) ; 
close file (customer) ; 
end; 

When run, the following is printed at the terminal: 
2194GSpectrograE*iics WOR 

this program could easily be modified to perform updates and/or 
additions to the file. 

EPP.OR HANDLING 

Ihe most ccanmonly encountered errors in the PI/I interface are KEY and 
RECCRD errors. It is a good idea to include on-units for these 
conditions in your programs, as veil as an ENDFILE on-unit for files 
opened for INPUT or UPDATE. 

Key Errors 

The KEY condition may be raised for several reasons, including: 

• The record with the indicated KEY cannot be found during a READ 
or REWRITE. 

• The program attempted to add a record with a KEY value that 
already exists in the file; duplicate keys are not allowed. 

• A partial KEY value is used during a READ or REWRITE (the use of 
partial keys is not supported) . 

• The size used in declaring the KEY variable during a READ is 
smaller than the default size indicated for the key in the index 
subfile (default for Pt/I-created files is 32 characters) . 

• Ihere is no more room to add keys in the primary index subfile 
(very rare; see Section 15 if this happens) . 

• The key value is in the wrong format or was not specified 
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properly; for example, the key might have been written as a 
fixed decimal and you are trying to read it back as a character 
string. (The reverse of the situation is also true.) 

As an aid in debugging, the ONKEY function (built-in) returns the value 
of the key that caused the KEY error. The following program contains 
KEY and ENIFILE on-units to trap errors that may occur vAiile performing 
file reads: 

readerr : 

proc options (main) ; 

/* this program shows the use of on-units in trapping KEY errors 
during file reads */ 

del err file file output; 

/* err_Tile is for error messages */ 

del onkey builtin; 

/* returns key value that caused error condition to be raised */ 

del badkey char (32) var; 

del sample file keyed sequential; 

del pkey char (32) ; 

del readvar char (30) var; 

del kvar char (32) var; 

/* KVAR is used with KEYTO option and must be CHAR VARYING */ 

/* Set up on-unit to handle file read errors */ 

on key(sample) begin; 
/* KEY condition is a caimon error */ 

badkey = onkey; 
/* assign value of error-causing key to BADKEY and print it out */ 

put skip file(err_file) list ('Bad key is:', badkey); 

goto pick_up; 

end; /* end on-unit */ 

/* set up an on-unit to handle end of file */ 

on end file (sample) begin; 

close file (sample) ; 

put skip list('Ehd of file'); 

stop; 

end; 
open file (sample) input; 
open file(err_file) ; 

/* the first READ doesn't have to be a keyed one */ 

read file(sample) into (readvar) ; 
put skip list (readvar) ; 

/* now read with bad key */ 



REV. 9-18 



im4558 THE PI/ 1 INTERFACE 

pkey = '0006'; /* no such key */ 

/* this should trigger on-unit for KEY */ 

read file (sample) into(readvar) key (pkey) ; 
put skip list(readvar) ; 

/* control comes here in event of an error */ 

pick_up: 

read file(sample) into(readvar) key('0001'); 

/* read top of file */ 

put skip list(readvar) ; 

close file (sample) ; 

close file(err_file) ; 

end; 
end; • 
/* run it */ 
OK, seg #readerr 

first file record 
first file record 

OK, 



Nate 

Both the KEY and the RECCM) conditions are always enabled and 
cannot be disabled. 



The RECCRD Condition 

The RECCSRD error condition is generally raised during a READ, WRITE or 
REWRITE operation v*ien the size of the record in the data subfile does 
not match the size of the variable into vAiich the record is being read 
or frcan viiich it is being written. The variable used may be too small 
or too large to acccanmodate the size of the data being read into it. 
PI/I donands that the record size and read-variable match exactly. In 
PI/I Subset G, the only way to avoid this error is to program carefully 
(and cross your fingers) . 
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Other Fbssible Error Conditions 

The UNDEFINEDFILE condition may be raised during an unsuccessful 
attempt to open a file. This can occur for a variety of reasons: 

• The filename is misspelled viien opening the file for INPUT or 
UPDATE. (Use of these access modes assunes the file exists.) 

• An attempt is made to open a non-existent file for INPUT or 
UPDATE. 

• Incomplete or conflicting attributes are specified during an 
OPEN or DECLARE FILE statanent. 

• Your version of PI/I has not been loaded with the proper MIDAS 
interface routines and/or proper libraries. 

• Your compiler is malfunctioning. 

In MIDAS files, if one of the segment subfiles is left open (due to 
program error or failure) an attempt to re-open the file will trigger 
this condition. Use CLOSE ALL (FRIMOS level ccstimand) to close the file 
before attonpting to re-run the program. 



locked Records 



If the program aborts and a record on the file remains locked, you must 
run MPACK to unlock the record as the record cannot unlock itself, 
locking usually occurs when the user hits CTRL-P or BREAK immediately 
following a READ operation. Ihe only way to tell if a record is locked 
is that v*ien you attempt to read that record an ERROR condition is 
signalled and the program will fail. At this point, you should run the 
MPACK utility using the UNLOCK option. (See Section 12.) 
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INTRODUCTIC»I 

RPG can be used to access MIDAS files just like any other type of file 

supported by Prime's RPG. Prime's RPG supports both keyed-index and 
direct access MIDAS files. In RPG, keyed-index MIDAS files are called 
Indexed files; they must be indicated with an "I" in colimn 32 of the 
File Description statement. (This section refers to the standard RPG 
coding "Specifications Sieet" as a "statement.") Direct access MIDAS 
files are specified as Direct files, with a "D" in column 32. CCBOL 
calls these files INDEXED SEQUENTIAL and RELATIVE files respectively. 



About This Section 

This section assumes you know RPG and 'understand the terms and concepts 
related to RPG file-handling. The purpose of this section is not to 
teach you how to use RPG, but rather how to use RPG to access a MIDAS 
file. In this section, you'll find the basic information needed to 
correctly describe and operate on a MIDAS file with an RPG program. 



LANGUAGE-DEPENDENT FEATURES 

Secondary keys and secondary data are not supported by RPG, so a file 
written and updated by RPG programs should not have these features. 
Ifewever, RPG can access a MIDAS file that has secondary keys and 
secondary data, but only by primary key. Other RPG restrictions on 
MIDAS files are: 

• The primary key in an Indexed file must be in the data record, 
but it does not have to be the first field in the record. 

• The primary key in an Indexed file must be no more than 32 
characters long. 

• The primary key in a Direct file must be defined as 
single-precision floating-point, using the "S" data type option. 
This is done during template creation: see Section 2. 

• The primary key in a Direct file is called the relative record 
nijnber. It is not piiysically resident in the data record and is 
therefore not defined as part of the data record in an RPG 
program. Ihe RPG program describes the record number as a 
standard numeric item. Ihe onty time you viorry about defining 
the relative record number is during template creation when you 
define the primary key as a single- precision floating-point 
number (see above) . 
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• Records cannot be deleted from a MIDAS file in RPG. 

• Primary key values cannot be changed in MIDAS, so the only part 
of a MIDAS file that can be updated from an RPG program is the 
data record. If the data record contains a copy of all the key 
values for that record, be careful not to change the key values 
v*iile updating, or you'll end up with severe discrepancies 
between the key values in the data file records and the key 
values in the secondary indexes. This applies only to MIDAS 
files that were built by an application program in another 
language or by KBUILD. 

• MIDAS files can be accessed randomly by key, if they're Indexed, 
or by relative record number, if they are Direct files, but only 
if designated as Chained files. 



Program Execution Requirements 

lb run an RPG program that accesses a MIDAS file, the following 
statanents must be included in every LOAD sequence to properly load all 
the libraries: 

LI RPGLIB /* RPG library 
LI KIDALB /* MIDAS library 
LI /* FOITRAN library 



RPGLIB is the RPG library, KIDALB is the MIDAS library and the FCHTOAN 
library is loaded with LI. For an example of a complete load sequence, 
see Compiling and Laading later in this section. 



DESCRIBING A MIDAS FILE IN RPG 

The first part of MIDAS file-handling in RPG is the definition process, 
v*»ich consists of correctly describing the MIDAS file to RPG via the 
File Description statement. Table 10-1 shows how to define a 
keyed-index or a direct access MIDAS file. Where necessary, the 
individual attributes are described in further detail below. 
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RPGII File Description deifications 
Ebr MIDAS Files 





Attribute 
File Type 

File Designation 




File Format 




Ftecord Length 




Mode of Processing 



• Key-Field Lsrqth 

• File Organization 

• tfey Col. Ppsition 

• Device 

w File Addition 



Oolunn(s) 
15 

16 

19 
24-27 

28 



29-30 

32 
35-38 

40-46 
66 



^Jhat to Specify 

Input (I), Output (0) or 

Update (U) but not Display (D) 

Primary (P) , Secondary (S) , 

Chained (C) or Demand (D) : 
left blank if an Output file 

Fixed length (F) 

The MIDAS data record length: 
includes primary key length 

Specify R for random, L for 
sequential within limits - for 
Indexed files only, or leave 
blank for sequential by key 



The length of the 
in characters: 
files only 



primary key 
for Indexed 



Indexed or Direct (I or D) 

Colunn vhere the primary key 
starts in the data record - for 
Indexed files only 

Must be disk (DISK) 

To add records to a non-empty 
Indexed file, specify an A in 
colunn 66. "Ihe records need 
not be added in sequential 
order. To load records into an 
empty Indexed file, define the 
file as an Output file (with an 
"0" in column 15) and put a U 
or a blank in colunn 66. U 
implies an unordered load; 
v*iere records may be input in 
random key order; a blank 
implies an ordered load. 
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Ifenns used in File Description 

Some of the attributes mentioned in T^ble 10-1 require a bit more 
explanation, as it may not be clear how they relate to MIDAS. This is 
just a brief explanation of how these terms apply to MIDAS file 
processing in RPG, so refer to a standard RPG text if you need further 
assistance. 

File Type Specification ; The following restrictions apply to MIDAS 
files as described in column 15 of the File Description statement: 

The file type (colunn 15) can be one of these: 

• I — Input (for reading only) * 

• — Qjtput (for writiiig only) 

• U — Update (for reading and writing) * 



* If an A occurs in colunn 66 of the File Description statement, 
new records may also be added to the file, if an ADD entry 
appears in colunn 16-18 of the Output statenent. 

Ebr further information on vAiat these file types mean, and the 
restrictions on them, see The RPG Programner's Guide . 

Notice that a MIDAS file cannot be described as a Display (D) file in 
RPG. 

File Designation Ftestrictions : The legal file designations for a 
MIDAS file, as indicated in colunn 16 are: 



• P — Primary: main file from vhich records are read — only one 
primary file should be specified per program. The Primary file 
can be opened for input or update. 

• S — Secondary: one or more files from vAiich records are read 
after Primary file is processed, if "matching" is not specified 
in columns 61-62 of the Input statement. If matching is 
indicated, secondary files are processed by standard RPG 
matching algorithms. Secondary files can be Input or Update 
files, and they are processed in the order in vtich they appear 
in the File Ifescription statements. 
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• C — Qiained: can be read randomly or loaded directly via t±e 
CHAIN operation code. Chained files can be opened for Input, 
Output or update. 

• D — Demand: can be input or update files. Use the READ 
operation code in the Calculation statanent to read from a 
Demand file. These files are processed sequentially by key. 

File Mdition Specifications ; Records can be added either 
sequentially or randcxnly to an Indexed (MIDAS) file. Jtecords cannot be 
added to a file opened for access under the sequential within limits 
processing mode, however. For an Indexed file opened for Input, 
Output, or Update, if an A is specified in colixnn 66, new records can 
be added in any order. For an Indexed file opened for Output, a blank 
indicates a load to an initially empty file where the records must be 
supplied in key order; a U in colunn 66 indicates an unordered load to 
an initially empty file. It is more efficient to add records in sorted 
order (by primary key value) , because then MIDAS doesn't have to sort 
them during the loading process. 

Records can be initially loaded to Direct files by specifying the file 
as Output Chained: use an "0^' in colunn 15, and a "C" in colunn 16. 
Records can be added to a Direct file that already contains entries by 
specifying the file as Update Chained: use a "U" in colunn 15 and a 
"C in column 16. In either case colunn 66 of the File Description 
statement, as well as colunns 16-18 of the Output statanent, should be 
left blank vAien processing Direct files. Note that relative record 
number values cannot exceed the nunber of records pre-allocated during 
tanplate creation. 



Modes of Processing 

The method in ^lich a MIDAS file is to be processed is indicated in 
colunn 28 of the File Ascription Specifications statement. The three 
modes of processing allowed on MIDAS files are: 

• L — Sequential within limits (for Indexed files only) 

• R — (1) Random by relative record nunber (Direct files) or (2) 
random by key (Indexed files) 

• blank — Sequential by key 

These modes of processing can be applied to MIDAS files depending on 
how these file are described in the File Designation colunn. 
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Primary, Secondary or Demand Files ; can be accessed by non-random 
access methods only. The particular access method (mode of processing) 
depends on on the file's organization. 

Organization Mode of Processing 

Direct Sequential by relative record number 

Indexed Sequential by key. Sequential within 

limits 

Ebr Chained Files ; MIDAS files declared as Chained files may be 
processed according to their organization. If the MIDAS file is 
Indexed, it can be accessed randomly by key. If the file is Direct, it 
can be accessed rarrianly by relative record number only. MIDAS files 
can only be accessed by key if they are defined as Chained files. 

Demand Files ; Demand files can be processed sequentially by key 
(applies to both Indexed and Direct files) , or sequentially within 
limits (for Indexed files only) . There are two methods of 
acccanplishing limits processing; using the SETLL operation in a 
Calculation statanent, or using a record address file (RAF). (Record 
address files are sequential files used to perform limits processing on 
Indexed files.) The first method specifies a lower limit for the 
primary key value with SETLL: the file can then be positioned to the 
proper record and can be processed from that point. The record address 
file method requires the creation of a separate "limits" file 
(sequential) vhich contains records that specify the "low" value fran 
which to start processing, and the "high" value at v*iich to stop 
processing, lb use the record address file method, yau must specify 
the name of this file in the Extensions statement (in columns 11-18), 
along with the name of the MIDAS file that is to be processed (colunns 
19-26) . See The RPG Programmer's Guide for details. 



FILE OPERATIONS 

The operations that can be performed on a MIDAS file vary with the file 
description in the File Description statanent. The standard file 
operations that can be performed on MIDAS files with an RPG program 
are: 

• Reading records — can be done sequentially or randomly by 
primary key or relative record number (Direct files) . A read 
always implies a position operation, and implies a lock 
operation if the file is opened for L^ate. (See Rasitioning 
the File for further details.) Reads are done in the normal 
Input cycle, or by a READ or CHAIN operation in a Calculation 
statement . 

• Adding records — is the addition of new records to a non-empty 
file. For indexed files this is possible for Input, Oitput, or 
Update files v^ere an A appears in column 66 of the File 
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Description statanent, and vi*ien ADD appears in colunwis 16-18 of 
the (Dutput statsnent. Itefer to Updating Records for an 
explanation of adding new records to a Direct file. 

• loading records — is the initial addition of records to an 
onpty MIDAS file. Ibis applies to both Indexed and Direct 
files. 

• L^xJating records — works only for files opened as Update files: 
an "update" is simply a read followed by a write. Ihis applies 
to Indexed or Direct files. The only way to add entries to an 
existing Direct file is to use an update operation. 

These operations are elaborated upon below. 



Positioning the File 

File position is thought of in terms of a "file pointer" vAiich always 
points to some record in the file. The record to which the file 
pointer is positioned is called the "current record", or the current 
file position. Qily a file designated as "Chained" (using a C in 
colunn 16 of the File Description) , can be positioned to a specific 
record in the file. File position is established using a CHAIN 
operation in the Calculation Specifications statement. When a file is 
CHAINed, usirg a specific primary key value, the file pointer positions 
to the record with this key value. This record then beccmes the 
current record and is read. If the file is opened for Update, the 
record will also be locked. towever, if the file is a Direct file 
defined as Qjtput Chained, the CHAIN operation causes a position only. 

Demand files can also be positioned, but only indirectly. "Ihis can be 
done by SETLL or with a record address file. The file position is 
established in tvo steps: first by setting the lower limit for the 
primary key with the SETLL operation in a Calculation statanent, or by 
RAF, and then performing a READ operation. The record positioned to 
will be the one \«4iose primary key value matches the lower limit value, 
if one exists. If this primary key value does not exist, the record 
v*iose primary key value is greater than the lower limit specification 
becanes the current record. 



Reading Records 

MIDAS files can be read as part of the normal Input cycle, or as part 
of the Calculation cycle, depending on their designation. Files v*iose 
records are read as part of the Input cycle are declared as Primary or 
Secondary and are read sequentially. Files declared as Demand can also 
be read sequentially from beginning to end using a SETLL operation, or 
by using a record address file to set an initial file position. 
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The read occurs during the READ operation of the Calculation statement. 
Records read from files declared as Chained are read randomly by 
primary or relative record key value using the CHAIN operation of the 
Calculation statonent. If the file is an Update file, the record will 
also be locked when positioned to and read. 

Sequential Reads on Indexed Files ; Indexed files read as a part of 
the normal Input cycle are read sequentially by key. Each record is 
read in primary key order, that is, in the order in which key values 
appear in the primary index subfile. After a record is read, RPG 
automatically advances the file pointer, making the next record (in 
primary key order) the current record. The next read operation then 
reads the current record, and again advances the file pointer to the 
next record, making it current. Files opened as primary or secondary 
files cannot be read randomly. 

Demand files can be read sequentially within limits in the tWD ways 
described earlier: see Demand Files under Modes of Processing , above. 

Random Reads ; Random reads can be done only on files designated as 
Chained files. Ihis applies both to Indexed and Direct files. Randan 
reads are performed by using the CHAIN operation in the Calculation 
statement. This method can be used on both Indexed files and Direct 
files. The primary key or relative record number is supplied to MIDAS, 
and the next record vAiose primary key matches this value will be 
returned. The indicator for "no record found" should be set (in 
colunns 54 and 55 of the Calculation statement) , enabling the program 
to recover if there is no record in the file with that key value or a 
given record number. 



Nate 

In Direct files, space is pre-allocated for every record upon 
template creation. If a legal record number is supplied in a 
CHAIN operation, but there is no corresponding record for that 
nimber, the record will be returned as blanks. Nate that this 
is different frcan CCBOL v^iich returns a "record not found" 
error in this case. RPG does not treat a read of a 
non-existent record as an error, as long as the record number 
is within the pre-allocated limit on record nimbers. 



Ajding Records 

Records can be added to a MIDAS file through standard RPG output 
methods or by using the KBUILD utility. See Section 3 for details on 
KBUILD. 
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In Indexed files that contain entries, if colunn 66 of the File 
Description statanent contains an A and colunns 16-18 of the Output 
statenent specify the ADD Operation, RPG can add records to the file. 
Ihe file can be opened for Input, Output, or l^ate. This applies only 
to files that have been initially loaded, that is, files that already 
contain entries. 

Direct access files do not support ADD because of their file structure: 
instead, addition of records is accomplished by an update. See 
Updating Records below. 



loading Records 

lb load an Indexed file, specify a U or a blank in colunn 66 of the 
File Description statement: U implies an unordered load v^ereas blank 
implies an ordered (sequential by key) load. ISbte that ADD is not 
entered in colunns 16-18 of the Output statonent during a load. 

lb load a Direct file, specify it as Output Chained and use the CHAIN 
operation in the Calculation statenent to indicate the relative record 
nunber for each record to be loaded. 



Updating Records 

lb update a MIDAS file record in RPG, the record must first be read and 
then updated in the Output cycle. Be careful not to change the primary 
key value vhen rewriting a record, because MIDAS does not allow the 
primary key value to be changed. This applies to both Indexed and 
Direct files. 

The only way to add new records to a Direct file that contains entries 
is to perform an update. Ihis is because RPG assunes that any record 
for Vi^ich space has been pre-allocated (by CREATK) , but v*iich vas not 
added during the initial load, exists as all blanks. Thus, any attempt 
to add a new entry to a direct access file is simply an update of the 
blanks that already appear in this "slot" in the file. 



Deleting Records 

There is no delete operation in RPG. In order to delete records, write 
a program to "flag" the records to be deleted, then copy the file to a 
new file, omitting the records vsihich were flagged for deletion. Ebr an 
idea of how this can be done, see the sample program called UPDATE 
under DIRECT FILE EXAMPLES. 
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Error Handling 

RPG flags all MIDAS errors but can only recover from conditions of 
"record locked" and "record not on file". The messages are described 
below. The general format of the messages are shown here. 

The general MIDAS error message is reported as: 

MIDAS [MIDAS error message number] filename 

(In some messages, the word MIDAS may be returned as "KIDA" instead, 
but the user should not be concerned, as the two terms mean the same 
thing.) Vtien a message of this type is encountered during file 
processing, the user should look up the error message nunber in 
/^pendix A of this book to determine the nature of the error, itote 
that MIDAS errors cannot be handled by typing an S followed by a 
carriage return. In general, such action should only be taken when the 
message returned by RPG explicitly permits this method of recovery. 

Record Locked ; The general "record locked" message is: 

filename keyfield RECORD IN USE. TYPE S(CR) TO TRY AGAIN. 

The record has been locked in anticipation of an update. Keyfield is 
the key that MIDAS was processing vAien the error occurred. If no other 
user is accessing the file, the file was not properly closed after 
previous usage. If another user is accessing the file, take the S(CR) 
option, otherwise close all files and perform the necessary steps, 
depending upon your application, to have a reliable file. If you type 
S followed by (CR) , the operation is executed again. 

CHAIN Errors: An unsuccessful CHAIN operation will invoke the 
message : 

♦♦♦♦UNSUCCESSFUL CHAIN TO ABOVE RECORD. TYPE S(CR) TO SKIP PAST OUTPUT. 

This message is returned v*ien a CHAIN operation has been attempted on 
the file and MIDAS was unable to retrieve the record. This is a 
serious message and indicates that the file is probably corrupted, or 
that the file is not a valid MIDAS file. Typing S(CR) restarts the RPG 
program cycle, skipping all the operations that wuld involve this 
record . 

Read Errors: The message for a general read error occurring at PRIMOS 
level is returned as: 

♦♦♦♦UNSUCCESSFUL READ AT LINE nn. 

This indicates an I/O error at the system level: users have no control 
over such errors. 
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MIDAS Concurrency Errors ; The MIDAS concurrency error message v\*iich 
RPG users may encounter is returned through RPG as: 

MIDAS CONCURRENCY ER 13, filename 
key 

key represents the key value vAiich RPG was processing at the time the 
error occurred. 

In a multi-user environment, it's possible for more than one user to 
access the same segment subfile (index) and get in each other's way. 
Usually, this message occurs when one user deletes a record that 
another user has locked for reading and/or update. Mthoigh this can't 
happen with two RPG users, it's conceivable that some FORTRAN or COBOL 
user may have the same file open for update while an RPG user is simply 
reading from it. The RPG user may get this mesage v*ien attanpting to 
update a now-deleted record. 



INDEXED FILE EXAMPLES 

"lb give you a general idea of how a MIDAS template can be created, 
populated and accessed through RPG, we've assatibled the following 
examples : 

• Creating the template for a keyed-index MIDAS file called MASTER 

• Listing of a record-loading program that adds employee data 
records to the empty MASTER file 

• Listing of a file-reading program which verifies that all 
desired records vere loaded 

• loading the two program.s 

• Output fron the read program — a sample report 

Creating the Ifemplate 

Ihe Indexed file MASTER is created using CREATK as sho^m in this sample 
session. The primary key is defined as an ASCII key of 10 characters 
in length. Ihe data size is defined as 32 words (64 characters) . User 
input is underlined to distinguish it from CREATK' s prompts. 
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[CREATK rev 17.6] 

MINIMIW OPTICAS? i^S 

FILE NAME? master 
NEW FILE? yes 
DIRECT ACCESS? no 

DATA SUBFILE QUESTIONS 

PRIMARY KEY TYPE: a 
PRIMARY KEY SIZE = : b 10 
EATA SIZE = : 32 

SECONDARY INDEX 

INDEX NO.? (CR) 

OK, 

Because RPG does not support secondary keys, we didn't define any for 
this file tanplate: instead, we hit a carriage return (CR) . 

Loading the File 

The following program, WAD, loads the file MASTER with employee 
records from a sequential disk file called SFILE. The primary key 
values are taken fran the employee number values in the sequential data 
file records. Ranember, only empty files can be loaded sequentially. 

The "H"" that appears at the top of the program is a Ifeader card, and 
is optional if no entries are to be included in it. 

H 

F* LOAD 

F* 

F* THIS PROGRAM LOADS THE INDEXED FILE MASTER WITH EMPLOYEE 

F* RECORDS FROM THE SEQUENTIAL DISK FILE SFILE. THE EMPLOYEE 

F* NUMBER IS USED AS THE INDEX. 

F* 

F* 

FSFILE IPE F 64 DISK 

FMASTER OF 64 5AI 2 DISK 

ISFILE NS 01 

I 2 60EMFNO 

I 7 64 DATA 

GMASTER D 01 

1 'P' 

EMPNO 6 

DATA 64 
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Ihe sequential file SPILE contains the following records: 



04416124An^MS 

22236124BRCWN 

25781125C00PER 

39840124EftVIS 

47124123EVANS 

66031123FOX 

73315125HOtMES 

80081125JONES 

86789123KELLER 

98570124IAKE 



200 380000 32000 

HY2345678900I2MH20000 800000 60000 

IG33344555502SH 450 750000 52000 

TV44455666601MH 250 400000 30000 

AS34567890100MH350001400000 120000 

FL4567890120!2MH 350 660000 26000 

EB56789012300MH10000 400000 30000 

CO00011222200SH 400 640000 64000 

ND99988777701MS 300 520000 38000 

MP88877666604SS300001200000 80000 



Reading an Indexed File 

When the program above is run, the records in the sequential file are 
added to the MIDAS file MASTER . "lb read the records back from the 
file and print out a report showing what's in the file, we use the READ 
program, listed below. The program reads MASTER sequentially and 
prints out a report in the file PRINT. 



H 

F* READ 

F* 



F* 

F* 

F* 

F* 

F* 

FMASTER 

FPRINT 

MASTER 



I 
I 
I 
I 
I 
I 
I 
I 
I 
I 
I 
C 
C 
C 
C 
C 
C 

c 

c 



itliu r'KwuKni'i rlCifijJb inij ±l^USLA£iU PirtOllLK r ILJj IN C3lLI^EiNTlAl, UKDEK 

AND mODUCES AN EMPLOYEE LISTING REPORT FRCM THE DATA. TOTALS 
ARE CALCULATED FOR CERTAIN CATEGORIES AND ARE SHOWN IN THE 
REPORT. 



IPEAF 
F 
NS 01 



64 

96 

1 CP 



5AI 



10 

10 

10 

10 

10 

10 

10 20 

10N20 



2 DISK 
PRINTER 



7 
10 
17 
19 
28 
30 
31 
32 
37 
44 
62 



PSTAT 

YTDG 

TOTAL 

GR<«S 

TAX 

PRATE 

HOURLY 

SALAR 



CCMP 'H' 
SUB YTDT 
ADD NETPAY 
AEO YTDG 
AID YTDT 
CCMP 300.00 
ADD 1 
ADD 1 



NETPAY 
TOTAL 
GROSS 
TAX 

HOURLY 
SALAR 



60EMPNO 
9 DEPT 
16 NAME 
18 INIT 
27 SSN 
290EXEM 

30 MSTAT 

31 PSTAT 
362PRATE 
432YTDG 
502YTDT 
62 DEL 

72 
82 
82 
82 



20 



02 



10 



20 
20 



10 
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OPRINT 


H 2 


IP 











OR 


OF 















UDATE 


Y 


8 













47 'EMPLOYEE LISTING' 













73 'PAGE' 









PAGE 


Z 


78 





H 


IP 











OR 


OF 



















8 'EMPLOYEE' 













19 'EMPLOYEE' 













32 'DEPARTMENT' 













39 'RATE' 













50 'Y-T-D' 













62 'Y-T-D' 













74 'Y-T-D' 





H 2 


IP 











OR 


OF 



















7 'NUMBER' 













17 'NAME' 













30 'NUMBER' 













50 'GRCSS' 













61 'TAX' 













72 'NET' 





D 


01 10 















EMFNO 




7 









NftME 




17 









INIT 




20 









DEPT 




29 









PRATE 


1 


40 









YTDG 


1 


52 









Yl'Di' 


1 


64 









NETPAYl 


76 







02 






78 '*■ 





T 1 


LR 



















14 'TOTAL SALARIED' 













25 'EMPLOYEES:' 









SALAR 


2 


28 









GROSS 


1 


52 









TAX 


1 


64 









TOTAL 


1 


76 





T 


LR 



















12 'TOTAL HOURLY' 













23 'EMPLOYEES:' 









H0URLY2 


28 



When compiled, loaded and executed, the program produces a report that 
looks like this: 



RT^/. P! 
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9/23/80 






EMPLOYEE LISTING 




PAGE 


EMPLOYEE EMPLOYEE 


DEPARTMENT 


RATE 


Y-T-D 


Y-T-D 


Y-T-D 


NUMBER 


NAME 




NUMBER 




GROSS 


TAX 


NET 


04416 


ADAMS 


WJ 


124 


2.00 


3,800.00 


320.00 


3,480.00 


22236 


BROWN 


HY 


124 


200.00 


8,000.00 


600.00 


7,400.00 


25781 


COOPER 


IG 


125 


4.50 


7,500.00 


520.00 


6,980.00 


39840 


DAVIS 


TV 


124 


2.50 


4,000.00 


300.00 


3,700.00 


47124 


EVANS 


AS 


123 


350.00 


14,000.00 


1,200.00 


12,800.00 


66031 


FOX 


FL 


123 


3.50 


6,600.00 


260.00 


6,340.00 


73315 


HOEMES 


EB 


125 


100.00 


4,000.00 


300.00 


3,700.00 


80081 


JONES 


CO 


125 


4.00 


6,400.00 


640.00 


5,760.00 


86789 


KEr,T.KR 


ND 


123 


3.00 


5,200.00 


380.00 


4,820.00 


98570 


LAKE 


MP 


124 


300.00 


12,000.00 


800.00 


11,200.00 


TOTAL 


SALARIED EMPLOYEES: 2 




71,500.00 


5,320.00 


66,180.00 



TOTAL HOURLY EMPLOYEES: 8 
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DIRECT FILE EXAMPLES 



Direct files require a slightly different type of template. The user 
must answer "yes" to the "DIRECT ACCESS?" question which CREATK always 
asks after requesting the file name and status. MIDAS then sets up the 
tanplate for direct access, allowing each record to have, and be 
accessed by, a unique floating-point record nunber. Ihe RPG user, v*ien 
creating a template for a Direct file, must always define the FKIMARY 
KEY TYPE as "S", which is the symbol for sirvgle-precision 
floating-point keys in MIDAS in an RPG program. The primary key is 
never mentioned in the description of the data record. The example 
below shows the sample user-CREATK dialog needed to set up the Direct 
file MASTD used in the remaining examples in this section. 



Creating a Direct File Tbmplate 

Ihe following CREATK session shows the input needed to define the 
Direct file MASTD, which is used in the ranaining examples to 
dotionstrate Direct file processing in RPG. 

OK, creatk 
[CREATK rev 17.6] 

MINIMUM OPTIONS? i«s 

FILE NAME? mastd 
NEW FILE? yes 
DIRECT ACCESS? yes 

DATA SUBFILE QUESTIONS 

PRIMARY KEY TYPE: s 

DATA SIZE = : 32 

NUMBER OF ENTRIES TO ALLOCATE? 100 

SECONDARY INDEX 

INDEX NO.? (CR) 

SETTING FILE LOCK TO N READERS AND N WRITERS 

OK, 

In this case, the file has fixed-length records of 32 words (64 
characters) . CREATK allocates 100 records for this file v^ien it sets 
up the template. Cnly record numbers between and 99 are legal for 
this file. 
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loading the File 

Ihe following program, DALQAD, loads an wupty Direct file using a 
sequential disk file, FILEIN. The sequential file appears below the 
program listing. 



H 

F* 

F* 

F* 

F* 

F* 

F* 

F* 

F* 

FFILEIN 

FWASTD 

IFILEIN 

I 

I 

I 

C 01 

CMASTD 











DALOAD 

THIS PROGRAM LOADS THE DIRECT ACCESS FILE MASTD WITH EMPLOYEE 
RECORDS FROM THE SEQUENTIAL DISK FILE FILEIN. THE RELATIVE 
RECORD NUMBERS OF THE FILE ARE SELECTED FRCM THE FIRST TWO 
DIGITS OF THE EMPLOYEE NUMBER. 



IPE 

OC 

NS 



F 
F 
01 



64 
64R 



D 



EMHJO 



01 



CHAIM^IASTD 



ENPNO 

EMPl 

DATA 



DISK 
DISK 



1 

3 

6 

64 



2 
4 
7 



30EMPNO 
60EMP1 
64 DATA 
99 



When compiled and loaded, the program is run 
MASTD file. 



to add records to the 



Reading the File 

Ihe followir^ program uses the just-loaded Direct file as a master file 
against which data in a transaction file can be checked. Ihe 
transaction file is a sequential file containing employee record 
information. Records are read frcsn the sequential file called iry^S 
and the MASTD file is then read to see if the information matches. Any 
data in the transaction file v*iich does not match the data in the MASTD 
file is marked vdth an asterisk (*) in the edit listing produced by the 
program. Note that the relative record number does not appear as part 
of the record description. 
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H 

F* 

F* 

F* 

F* 

F* 

F* 

F* 

F* 

E* 

FMASTD 

FTRANS 

FLISTl 

ITRANS 

I 

I 

I 

I 

I 

I 

I 

I 

IMASTD 

I 

I 

C 

C 

C 

C 

c 
c 
c 
c 
c 
c 
c 
c 
c 
c 



DAREAD 

THIS PROGRAM CHECKS THE SEQUENTIAL TRANSACTION FILE FCR ERRCRS 
AND reODUCES A CURRENT EARNINGS EDIT LISTING. TESTS ARE MADE 
FCR THE C0RIM:T "reANSACTION COEE, FOR THE CCPRECT DEPARTMENT 
NIMBER, AND ALSO FOR A EMPLOYEE NUMBER MATCH WITH THE DIRECT 
ACCESS FILE MASTD. 



IC 
IPE 

NS 



F 
F 
F 
01 



64R 
64 
120 



DISK 
DISK 
PRINTER 



NS 02 1 CP 



01 

01 

01N20 

01N20 

01 



N20 
21 
01 
N22 
01 
01 
01 
01 
01 

OLISTl 































01 
01 

01 



DEPT 

DEPT 

DEPT 

EME^JO 

ERRDEP 

ERRfflP 

CODE 

ERRRC 

TOTOH 

TOTOH 

TOTG 

TOTT 

TOTAL 



SETON 
COMP 125 
CCMP 124 
COMP 123 
CHAIJ»1ASTD 



ADD 

AH) 

COMP 

AK) 

ADD 

ADD 

ADD 

ADD 

ADD 



1 
1 
'C 

1 

RHOURS 

OHOURS 

GROSS 

TAX 

1 



H 
OR 



H 
OR 



11 



IP 
OF 



IP 
OF 



1 
8 

10 
13 
25 
29 
33 
38 

2 

4 



1 cora: 

90EMFNO 
120EMFNO2 
150DEPT 
282RHOURS 
3220HOURS 
372GROSS 
422TAX 

30MEMPNO 
60EMFNO2 
30 
20 
20 
20 



21 



ERRDEP 
ERREMP 

ERRRC 

TOTRH 

TOTOH 

TOTG 

TOTT 

TOTAL 



20 
20 

20 
52 
52 
62 
62 
20 



22 



38 
53 



4 
12 
21 
30 
39 
48 
57 



•CURRENT EARNIN' 
'GS EDIT LISTING' 



■CODE' 
• EMP NO' 
'DEPT NO' 
'REG HRS' 
'OTM HRS' 
'GROSS' 
'TAX' 



D 1 



30 



CODE 



REV. 



10 



18 





EMFNO 


9 




EMFN02 


12 




DEPT 


19 




RHOURSl 


29 




OHOURSl 


38 




GROSS 1 


48 




TAX 1 


58 


30N22 






30 21 






30N20 






N22 




3 


21 
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D 1 

CK 

OR 

N22 3 '*' 

21 10 '*• 

N20 18 •*' 

76 "CHECK FOR ERRORS' 

T 2 LR 

21 'TOTALS' 

TOTRH 2 29 

TOTOH 2 38 

TOTG 2 48 

TOTT 2 58 

T 1 IB. 

14 'ERROR RECORDS:' 

27 'RECORD CODE-' 

ERRRC 2 29 

47 'EMPLOYEE Nlfl»1BER-' 

ERREMP2 49 

69 'DEPARTMENT NIB^BER-' 

ERRDEP2 71 

T 1 LR 

15 'TOTAL RECOTO^ P' 

24 'ROCESSED:' 

TOTAL 2 27 

The sequerxtial disk file TRANS, v*iose data records are checked for 
errors,- contains the followinq information: 



c 


04416123 


4000 500 9500 


950 


c 


22236124 


0000 00020000 


1500 


c 


25781125 


4000 00018000 


1300 





39840122 


4000 00010000 


750 


c 


47124123 


0000 00035000 


3000 


c 


66013123 


4000 30015575 


808 


c 


68726124 


0000 00040000 


4000 


c 


73315125 


0000 00010000 


750 


D 


74249123 


0000 00025000 


1750 


C 


80081152 


3500 00014000 


1400 


c 


86789123 


4000 00012000 


950 


c 


98570124 


0000 00030000 


2000 



After the psrogran has been compiled, loaded and run, the printer file, 
LISTl, looks like this: 
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CURRENT EARNINGS EDIT LISTING 



IDE 


EMP NO 


DEPT NO 


REG HRS 


OTM HRS 


GROSS 


TAX 


C 


04416 


123 


40.00 


5.00 


95.00 


9.50 


C 


22236 


124 


.00 


.00 


200.00 


15.00 


C 


25781 


125 


40.00 


.00 


180.00 


13.00 





39840 


122 


40.00 


.00 


100.00 


7.50 


* 




* 










c 


47124 


123 


.00 


.00 


350.00 


30.00 


c 


66031 


123 


40.00 


3.00 


155.75 


8.08 


c 


68726 
* 


124 


.00 


.00 


400.00 


40.00 


c 


73315 


125 


.00 


.00 


100.00 


7.50 


D 


74249 


123 


.00 


.00 


250.00 


17.50 


* 


* 












c 


80081 


152 
* 


35.00 


.00 


140.00 


14.00 


c 


86789 


123 


40.00 


.00 


120.00 


9.50 


c 


98570 


124 


.00 


.00 


300.00 


20.00 



CHECK FOR ERRORS 



CHECK FOR ERRORS 



CHECK FOR ERRORS 



CHECK FOR ERRORS 



TOTALS 235.00 8.00 2,390.75 191.58 
ERROR RECORDS: RECORD CODE- 2 EMPLOYEE NUMBER- 2 DEPARTMENT NUMBER- 2 
TOTAL RECORDS PROCESSED: 12 



REV. 



10 - 20 



IDR4558 THE RPG INTERFACE 



Updating Records 

In Update mode; new records can be added to a file (if it already 
contains data) , and existing data records can be rewritten. Updates to 
a Direct file can be done using a sequential file vdnich tells the 
update program viAiat to do with certain records in the Direct file. The 
sample program UPDATE shown below uses the file MAINT to indicate vAiich 
records in the MASTD file will be updated, added or effectively 
"deleted" . Records are not deleted physically, but appear to have been 
deleted v*ien the report which UPDATE produces is printed out. The 
report is done to verify that all the proper alterations have been made 
to the file. 

The file MAINT contains the following information: 

MA23712123CARSON BG99977555500SH 300 470000 47000 

MA70345125HARRIS CH44466888802MS325001150000 105000 

MD39840 

MD80081 

MD98570 

MU22236124MCB3AN 2MS20000 

MU25781125COOPER 02SH 500 

MU74249124IRVING 03MS25000 

MU86789123KELLER 1MS15000 

A listing of the UPDATE program begins on the next page. 



10 - 21 Cfctober 1980 



SECTICN 10 



im4558 



H 
F* 
F* 
F* 

F* 

F* 

F* 

F* 

F* 

FMASTD 

FMAINT 

FLIST2 

IMASTD 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

IMAINT 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

C 

C 

c 



UPDATE 

THIS PROGRAM UPDATES THE DIRECT ACCESS MASTD FILE VIA THE SEQUENTIAL 
MAINTENANCE FILE. THIS RESULTS IN ADDITIONS, DELETIONS AND UPDATES. 
A REPORT IS GENERATED TO LIST THE CHANGES THAT WERE MADE TO THE 
MASTER FILE. 



UC F 
IPE F 
F 
NS 



64R 
64 
120 
L CP 



AA 01 1 CM 2 CA 



BB 02 1 CM 2 CD 



CC 03 1 CM 2 CU 



N01 
01 
03 



TEME^O 
TEMKJO 
DEPT 



CHAIhMASTD 
CHAIlsMASTD 
CCMP TDEPT 



DISK 




DISK 




PRINTER 




2 


30EMPNO 


4 


60EMFNO2 


7 


90DEPT 


10 


16 NAME 


17 


18 INIT 


19 


27 SSN 


28 


290EXEM 


30 


30 MSTAT 


31 


31 PSTAT 


32 


362PRATE 


37 


432YTDG 


44 


502YrDT 


62 


62 DEL 


3 


ABTmPtiO 


5 


70TEMP2 


8 


100TDEPT 


11 


17 TNAME 


18 


19 TINIT 


20 


28 TSSN 


29 


300TEXEM 


31 


31 "IMSTAT 


32 


32 TPSTAT 


33 


372TPRATE 


38 


442TYTDG 


45 


512TYrUT 


3 


40TEMPNO 


5 


70TEMP2 


3 


40TEMPNO 


5 


70TEMP2 


8 


100TDEPT 


11 


17 TNAME 


18 


190TEXEM 


20 


20 IMSTAT 


21 


21 TPSTAT 


22 


262TPRATE 




HI 




40 




11 
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C 03 NAME COMP TOAME 12 

C 03 EXEM CCMP TEXEM 13 

C 03 MSTAT CCMP 1MSTAT 14 

C 03 PSTAT CCMP TPSTAT 15 

C 03 TOATE COMP TPRATE 16 

C 01 AISDS ADD 1 ADDS 20 

C 02 lELS ADD 1 EELS 20 

C 03 CHNGES MB 1 CHNGES 20 

0LIST2 HI IP 

CH OF 

43 'EMPLOYEE MASTER' 

60 • FILE MAINTENANCE' 

HI IP 

OR OF 

1 "C 

6 'EMP' 

12 'DEPT' 

24 'FW' 

39 'NO' 

42 'M' 

45 'S' 

77 'DE' 

H 2 IP 

OR OF 

1 'D' 

5 'NO' 

11 'NO' 

18 'NAME' 

24 '11' 

35 'SOC SBC NO' 

39 'EX' 

42 'S' 

45 'H' 

53 'RATE' 

64 'YTD GROSS' 

73 ' YTD TAX' 

77 'CD' 

D 1 01 

TEMFNO 4 

TEMP2 7 

TDEPT 11 

TNAME 20 

TINIT 24 

TSSN 34 

TEXEM 1 39 

TMSTAT 42 

TPSTAT 45 

TPRATEl 53 

TYTDG 1 64 

TTFUr 1 74 

88 'NEW RECORD' 

D 1 02 

1 -p> 

EMPNO 4 
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EMPN02 


7 









DEPT 


11 









NftME 


20 









INIT 


24 









SSN 


34 









EXEM 1 


39 









MSTAT 


42 









PSTAT 


45 









PRATE 1 


53 









Yl'DG 1 


64 









Yi'DT 1 


74 











77 'D' 











84 'DELETE' 




D 1 


03 















1 'P' 









EMPNO 


4 









EMPN02 


7 









TDEPT 


11 







Nil 




12 '*• 









TNAME 


20 







N12 




21 '*' 









INIT 


24 









SSN 


34 









TEXEM 1 


39 







N13 




40 '*' 









TMSTAT 


42 







N14 




43 '*' 









TPSTAT 


45 







N15 




46 •*' 









TPRATEl 


53 







N16 




54 '*• 









YTDG 1 


64 









Yrm' 1 


73 











84 'CHANGE' 




T 1 


LR 















14 'RECORDS 


ADDED-' 







ADDS 2 


16 











40 'RECORIE 


INACTIVATED-' 







DELS 2 


42 











62 'RECORDS 


CHANGED-' 







CHNGES2 


64 




OMAS'i'D D 


01 40 















1 'P' 









TEMPNO 


6 









TESIPT 


9 









TNAME 


16 









TINIT 


18 









TSSN 


27 









TEXEM 


29 









TMSTAT 


30 









TPSTAT 


31 









TPRATE 


36 









TYTDG 


43 









TYTDT 


50 
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62 • ' 

D 02 

62 'D' 

D 













When run, the UPDATE program produces this report; 



03 






Nil 


TDEPT 


9 


N12 


TNAME 


16 


N13 


TEXEM 


29 


N14 


TMSTAT 


30 


N15 


TPSTAT 


31 


N16 


TPRATE 


36 
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EMPLOYEE MASTER FILE MAINTENANCE 



C EMP EEPT 

D NO NO NAME 



FM NO M S 

II SOC SEC NO EX S H 



DE 
RATE YTD GROSS YTD TAX CD 



23712 123 


CARSON 


BG 999775555 


00 


S 


H 


3.00 


4,700.00 


470.00 




NEW RECORD 


70345 125 


HARRIS 


CH 444668888 


02 


M 


S 


325.00 


11,500.00 


1,050.00 




NEW RECORD 


P 39840 124 


DAVIS 


TV 444556666 


01 


M 


H 


2.50 


4,000.00 


300.00 


D 


mLETE 


P 80081 125 


JONES 


CO 000112222 


00 


S 


H 


4.00 


6,400.00 


640.00 


D 


DELETE 


P 98570 124 


LAKE 


MP 888776666 


04 


S 


S 


300.00 


12,000.00 


800.00 


D 


DELETE 


P 22236 124 


MORGAN 


* HY 234567890 


02* 


M 


S* 


200.00 


8,000.00 


600.00 




CHANGE 


P 25781 125 


COOPER 


IG 333445555 


02 


S 


H 


5.00* 


7,500.00 


520.00 




CHANGE 


P 86789 123 


KELLER 


ND 999887777 


01 


M 


S 


150.00* 


5,200.00 


380.00 




CHANGE 


RECORDS ADDED- 2 


RECORDS INACTIVATED- 


3 




RECORDS CHANGED- 3 
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SECTICN 11 
DIRECT ACCESS 



INTRODUCTION 

Direct access MIDAS files are supported by the FORTRAN, CCBOL and RPGII 
interfaces. Ibwever, such files are particularly well-suited for use 
with CCBOL, vAiich treats them as standard RELATIVE files. This section 
explains the structure of a direct access file and how to create a 
direct access file tonplate. Since each of the three language 
interfaces to MIDAS that support direct access files do things a little 
differently, we make no attonpt to lunp them all together. Instead, 
only the CCBOL direct access interface is discussed in this section. 
For information on using direct access in FORTRAN and in RPG, see 
sections 6 and 10 of this book. 

Mhat Is Direct Pccess? 

Direct access in MIDAS is based on record nunbers; each record in the 
file has a unique floating-point record nunber (single-precision) that 
identifies that record absolutely. lb get a particular record, one 
simply provides MIDAS with the right record nunber and the record is 

blocks in search of a value (which may have mistakenly gotten inserted 
in the wrong spot) , because direct access involves calculating the 
exact physical location of the record in the file using an algorithm 
that takes into account the record size, segment size, and so forth. 
The user doesn't need to worry about this except to know that MIDAS 
takes care of it all internally. The only dravfoack to direct access is 
that the user must keep track of the correlation between record nunbers 
and record values in order to locate irdividual records. 

Direct Arcess File Structure 

A direct access file template is created with CREATK in much the way as 
are keyed-index MIDAS files. In fact, the dialogs used are virtually 
identical, except for a few pranpts, v*iich are shown in the sample 
dialog a bit later in this section. The basic differences between 
keyed-index and direct access MIDAS files are: 



• A direct access (RELATIVE) file must have fixed-length records; 
the user must supply the record ler^th (data size) in words. 

• Each record in a direct access file must have a unique record 
nunber. Ihe record nunber may or may not have to be the {Mfimary 
key: this restriction depends on the language interface being 
used to access the file. 
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• Storage space must be pre-allocated for a direct access file, 
v*iich means that the user must estimate the maximum number of 
entries v*iich will eventually reside in the data subfile. 
CREATK then allocates the proper amount of space required to 
accommodate a file with the nunber of records the user 
indicated. 

• Direct access MIDAS files take up a bit more disk space than 
keyed-index files because a two-word record number is stored 
with each primary index entry. (Ihis is true even vAien the 
primary index is defined as the record number.) 

As mentioned in section 1, direct access files are accessible by the 
MIDAS direct access method, but they can also be accessed by the 
keyed-index method if keys are included in the file tonplate. This 
applies to FORTf^AN only. 



DIRECT ACCESS IN EACH LANGUAGE 

Ihe three language interfaces that support the direct access feature of 
MIDAS each implonent it a bit differently. The following paragrapiis 
summarize the treatment of direct access in CCeOL, FORTRAN and RPG. 



Direct Access in CCBOL 

COBOL treats direct access MIDAS files as RELATIVE files, using the 
standard RELATIVE file I/O statements, with a few minor enhancements, 
as CCBOL's interface to direct access MIDAS files. The RELATIVE KEY in 
a RELATIVE file is the primary key yDU defined for that MIDAS file 
during template creation. It is a COBOL requirement that the RELATIVE 
KEY be the relative record number field in each record: therefore, the 
primary key for a direct access MIDAS file to be accessed as a CCBOL 
RELATIVE file must be defined in a special way. 

Defining the Primary Key (in CREATK) : From the CCBOL programmer's 
point of view, the primary key would be thought of as a character 
string frcan one to six characters (bytes) in length. However, you must 
specify the primary key in bit string form vAien creating a direct 
access template with CREATK. This means that the primary key is always 
defined as being from 8 bits to 48 bits in length: this corresponds to 
a character string with a minimun size of one character and a maximum 
size of six characters. This allows for a maximum of 999,999 entries 
in the file, because 999999 is the largest relative record number 
possible in a RELATIVE file under Prime's CCBOL. 
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Declaring the RELATIVE KEY in the Program ; A corresponding PICTURE 
clause must be used to define the RELATIVE KEY in any program that 
accesses a RELATP.'E file: for example, a 48=bit string wauld have a 
PICTURE clause of 9(6) . 

Cbserve that reducing the RELATIVE KEY size from 48 bits decreases the 
maximun nixnber of entries that the file can accanmodate. For example, 
if the KEY is defined as a 32^3it string, the file can have a maximum 
of 9999 entries, as opposed to 999,999 entries. Ihe PICTURE clause 
that wDuld describe this particular key in a program is PIC 9(4) . In a 
CCBOL program that accesses a RELATIVE file, the RELATIVE KEY cannot be 
declared as part of the data record; instead, it is declared in the 
WCRKING STORAGE section. 

Secondary keys are not supported in RELATIVE files because CCBOL 
provides no mechanism for adding entries to secondary index subfiles. 
Ihese points are explained further under RELATIVE FILE ACCESS, below. 



Direct Access in FORTRAN 

Direct access files in FORTRAN do not require that the record ntmber be 
defined as a primary or secondary key. Ibwever, the user may define 
the record number as the primary or a secondary key if desired, keeping 
in mind that the record number is stored by MIDAS as a single-precision 

be a key field, the primary key should be defined as some other unique 
field in the record. In addition, up to 17 secondary indexes may be 
defined during template creation. 

If you choose not to make the record nunber a key field, you don't have 
to worry about it at all during template definition. The only time yau 
need to be concerned about the record nunber is vhen adding entries to 
the file. Then, a unique record number must be supplied for each 
record to be added to the data subfile. MIDAS takes care of storing 
the record nunbers in the proper place. 

Direct access files can be built (populated) by KBUILD, as described in 
Section 3; record nunbers must be supplied by the user and must appear 
in the same word position in each record. "lb access direct access 
files by record nunber (instead of by key) , the same basic subroutine 
calls are used, but the communications array format is slightly 
different. Efetails on access methods are covered in Section 6. 
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Direct Access in RPG 



RPGII supports direct access MIDAS files as standard RFG direct files. 
When a direct access MIDAS file template is created specifically for 
use with RPG, the primary key must be defined as a single-precision 
floating-point nuonber. Specify "S" in response to the "PRIMARY KEY 
TYPE:" prompt of the CREATK dialog. In RPG programs that process 
direct access files, the file organization must be specified as Direct 
(D) and the file can only be opened as a Chained file. Records are 
read randanly by record nunber. See Section 10 for specifics. 



CREATING A DIRECT ACCESS FILE 

Ihe CREATK dialog for setting up a direct access template is very much 
the same as the dialog used to set up a keyed-index file tonplate. lb 
invoke the dialog, simply type CREATK, and answer "YES" to the "DIRECT 
ACCESS?" prcxnpt. The important parts of the dialog are discussed 
below, and several examples are provided to illustrate how it is used. 
In creating a direct access file, you may choose either the minimum 
options path by answering "YES" to the MINIMUM OPTIONS?" prompt, or 
the extended options path, viiich is described in Section 15. 



CREATK Dialog for Direct Access 

The dialog used to set up a direct access template under minimun 
options is explained below. Most of the prompts are identical to those 
already shown in Section 2. 
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Prompt 
MTMTMiw ntyrrnwcr? 

FILENAME? 
DIRECT ACCESS? 



Response 



EATA SUBFILE QUESTIONS 
PRIMARY KEY TYPE: 



Srtx jJ^l/ll\ J. J!\j^ i. L^ J. £4 i-t^ e 



DATA SIZE=: 



NUMBER OF ENTRIES TO 
ALLOCATE? 



VPC 



Ehter pathname of file to be 
created . 

Ehter YES: signifies that file 
is to be set up for direct 
access and that it can be 
accessed by record nunber: 
records will be stored in the 
data stbfile in sequential order 
by record number. 



Fbr files to be used with COBOL, 
enter "b" for bit string; for 
files used with RPG, specify 
"s"; for FCBTERAN, any of the 
key types supported by CREATK 
are okay. (See TSble 2-2 in 
Section 2.) 

from 8 to 48 bits; for FORTRAN, 
replies should be made in 
accordance with the data type 
specified above. (See Section 
2.) 

Supply a value other than zero: 
direct access files must have 
fixed-length records. Do not 
simply hit (CR) in response to 
this pranpt. Record size should 
be supplied in vrords. 

Ehter maximun number of entries 
(records) for vhich to reserve 
room in the data subfile. 
CREATK must pre-allocate space 
for a direct access file. 



SECONDARY INDEX 
INDEX NO? 



Ehter an index nunber from 1-17 
if secondary keys are desired. 
Ihis feature applies to FORTRAN 
only; C<BOL or RPG users should 
simply hit carriage return (CR) , 
as a response to this prompt. 
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Ihe remaining prcxnpts in the dialog are the same as those of the 
keyed-index dialog discussed in section 2. 



Sample CREATK Session 

The following is taken frcm a terminal session in which a direct 
access template was created for a MIDAS file to be used with CCBOL. 

OK, creatk 
[CREATK rev 17.6] 

MINIMUM OPTIONS? yes 

FILE NAME? dacust 
NEW FILE? yes 
DIRECT ACCESS? yes 

DATA SUBFILE QUESTIOOS 

PRIMARY KEY TYPE: b 

PRIMARY KEY SIZE = : b 48 

DATA SIZE = : ^ 

NU^BER OF ENTRIES TO ALLOCATE? _15 

SECONDARY INIEX 

INDEX NO.? (CR) 

SETTING FILE LOCK TO N READERS AND N WRITERS 

OK, 

Because we want to use the file in a CCeOL application, no 
secondary keys were defined for this file template. 



RELATIVE FILE ACCESS 

As stated earlier, CCBOL' s method of accessing direct access files 
is the standard COBOL RELATIVE file interface. It consists of the 
READ, WRITE, REWRITE, DELETE and START statements. The standard 
OPEN and CLOSE statements are used to open and close the file fran 
a COBOL program as shown in Section 7. 

The remainder of this section deals with CCBOL' s RELATIVE file I/O 
statonents and how they are used in reading, writing, rewriting and 
deleting records from a direct access MIDAS file. Because they are 
so similar in syntax and usage to the INDEXED SEQUENTIAL 
statQtients, the reader is often referred to Section 7 for 
explanations to avoid duplication. 



REV. 11 



im4558 DIRECT ACCESS 



Definir>g the File 

Ihe SELECT statement^ discussed m Section 1, defines the file's 
logical name and organization. The differences between the SELECT 
statement for an INDEXED SEQUENTIAL file and a SELECT for a 
RELATIVE file are the CBGANIZATION clause specification and the the 
terms used to describe the primary key. The format indicates these 
differences: 

SELECT filename 

ASSIGN TO PEMS 

ORGANIZATION IS RELATIVE 



(sequential] 
RANDOM > ] 






DYNAMIC I 

[RELATIVE KEY IS key-name-1] 

[FILE STATUS IS status-code] . 

RELATIVE KEY is the primary key and represents the record number in 
a direct access file. It should be defined as a bit string during 
template creation. However, vhen accessing the file through a 
program, the RELATIVE KEY is treated as a character string with a 
minimun size of one character and a maximun size of six characters. 
This RELATIVE KEY should not be included in the DATA RECORD 
description in the File Definition section of the program. 
Instead, it should be defined only in the WCHKING STORAGE section. 
The key need not be specified if the file is opened for SEQUENTIAL 
access. (See Access Modes below.) 

Basically, all the rules that govern the RECORD KEY definition in 
INDEXED SEQUENTIAL files apply to RELATIVE files, with the 
following additions: 



• Ihe RELATIVE KEY is a character string defined as a bit 
string during template definition and must represent the 
record nunber in each file record. 

• The RELATIVE KEY cannot have a value larger than 999,999 or 
a PICTURE clause larger than 9(6) . 

• The RELATIVE KEY named by key-name-1 must be defined in the 
Wbrking Storage section, and not m the Record Description 
for that file. 
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Access Modes ; Ihe access modes are the same as for INDEXED 
SEQUENTIAL files; see Section 7 for details. The correspondence 
between access modes and "open" modes and v*iat can be done in each 
situation is shown in Table 11-1. If the file is opened for 
SEQUENTIAL OUTPUT, it is not necessary to define the RELATIVE KEY 
in the program because it is supplied by the CC60L run-time 
library. If you do not define a key in the SELECT statement, it 
defaults to a 6-byte character string, which is the maximum size 
allowed . 

The status codes returned in status-code are listed in Table 11-2. 

Condition Handling 

The INVALID KEY and AT END clauses may be included in RELATIVE file 
I/O statements as indicated in the formats given here. These 
statements are identical in format to those used in INDEXED file 
handling, explained in Section 7. The status codes returned to the 
program during RELATIVE file processing are listed in Table 11-2. 
Be sure to handle all common file processing conditions like 
"end-of-file" and "record not found" and so forth. 

Here is a summary of the condition handlers that can be used to 
trap run-time errors and conditions during RELATIVE file 
processing : 



• The AT END clause, v^ich defines one or more statanents 
v*iich are executed v*ien an "end-of-file" is detected. "This 
statements or statements may or may not direct control to 
some "end-of-file-handling" statements or procedure at 
another location in the program. 

• The INVALID KEY clause, viiich is executed when an error 
occurs; it specifies a statement or series of statements 
which perform some useful action or series of actions in the 
event of a KEY error. This statements or series of 
statements may or may not direct control to another location 
in the program where the error can be handled appropriately. 
(Can be used in START, READ, WRITE, REWRITE and DELETE 
statements.) 

• The USE AFTER ERROR statement v*iich indicates the name of a 
procedure in the program v^iich will be executed in the event 
of an I-O error, in addition to the System's standard I-O 
procedures. 
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RELATIVE I/O 



File Access 
Mode 


Statement 


Open Mode 


Input 


Output 


Input-Output 


Sequential 


READ 


• 




• 


WRITE 




• 




REWRITE 








START 


• 






DELETE 








Random 


READ 


• 






WRITE 




• 




REWRITE 








START 








DELETE 








Dynamic 


READ 


• 






WRITE 




• 




REWRITE 








START 


• 






DELETE 






^ 
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Table 11-2. RELATIVE File Status Cbdes 
Status Cede Interpretation 

00 Successful ccanpletion of operation. 

10 End of file encountered during a READ. 

21 User has attanpted to write beyond predefined 
boijndaries of the file. 

22 Record already exists in data subfile; user 
attempted to add a record with a non-unique 
record number. 

23 Record not found; no record found with the 
specifed key value. 

24 Boundary violation: user has attempted to 
read or write beyond pre-allocated file 
boundaries. (Boundaries are allocated by 
CREATK during template creation.) 

30 Permanent I/O error; could be a parity error, 

data check or transmission error. 

(Status Codes beginning with 9 are Prime-defined condition 
codes.) 

90 Locked record; attanpt to access a record 
already locked by another user or process. 

91 Uhlocked record; REWRITE attanpted without 
first locking the record with a READ. 

94 MIDAS concurrency error: another user has 
deleted the record you vfere trying to access. 

95 User has supplied a record length for a 
RELATIVE file that does not match the record 
size assigned to the file during template 
creation. 

96 Relative record number error; user supplied a 
record nuntier larger than the number 
pre-allocated by CREATK. 
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98 Attempt to do an indexed add to a direct 
access file; can't add entries to a RELATIVE 
file even if it's opened for INDEXED access. 

99 SystCTi error; possibly serious. Before 
panicking, verify that error is not due to a 
START that encountered a locked record. 
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Opening and Closing the File 

A direct access file is opened using the OPEN statement: 

(INPUT I 
OUTPUT? filename 
I-O ) 

Direct access files may be opened for INPUT, OUTPUT or I-O: 

• INPUT means READ only. 

• OUTPUT means WRITE only. 

• I-O means all operations are legal including READ, UPDATE, 
DELETE and WRITE. 

In SEQUENTIAL access mode, a RELATIVE file cannot be opened for I-O 
if a WRITE statement is included for this file; instead, it must 
be opened for OUTPUT only. Chly anpty files can be opened for 
SEQUENTIAL OUTPUT. OUTPUT mode prevents the accidental movanent of 
the record pointer while COBOL is trying to add records in 
sequential record order, because the only operation legal in OUTPUT 
mode is a WRITE. CCBOL provides its own record numbers in 
SEQUENTIAL WRITES, ignoring any values the user might have supplied 
for the relative record number field. 



tfote 

When a RELATIVE file is opened for writing in SEQUENTIAL 
access mode, it must be OPENed for OUTPUT: it cannot be 
opened for I-O. The file is assumed to be enpty (that is, 
it contains no entries) . 



Closing the File : The file is closed using the CLOSE statement: 
CLOSE filename-1 [ ,filename-2. ..] 

Put the CLOSE statanent at the logical end of the program or in an 
error-handling routine. It's possible to close more than one file with 
a single CLOSE statonent. 



ADDING RECORDS TO A RELATIVE FILE 

Because RELATIVE files in COBOL do not support the use of secondary 
keys, adding a record to a direct access file consists of simply 
supplying the record number and the data to be added to the data 
subfile. It is not possible to add secondary index entries to a 
RELATIVE file. 
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Two Vfeys to Md Records 

Because of their structure, RELATIVE files must be handled a little 
differently than INDEXED files v*ien populating them. If a file is 
empty (contains no record or index subfile entries) , you can add 
records to that file in any of the three access modes. Itowever, once a 
file contains entries, you can no longer add records to it in 
SEQUENTIAL access mode. Ihis is because SEQUENTIAL access mode is 
specifically intended for intial loading of records, that is, for 
populating empty files. RANDOM and DYNAMIC access modes are itKist 
useful for inserting records anyviiere in a file that already has 
entries. Both RANDOM and DYNAMIC access modes allow users to supply 
their own record numbers for each record to be added to the file. 



The WRITE Statement 

The WRITE statement is used, in all three access modes, to add records 
to a RELATIVE file. Ihere are tvro methods of record addition possible: 
the first, available in SEQUENTIAL mode , lets CCBOL supply the record 
numbers for each record — the user just supplies the data record 
information. This is known as "loading" or "initially loading" a file. 
The file must be empty in order to be loaded. The "randan" method, 
available in the other two access modes, requires that the user supply 
a record nunber for each record added. In this type of record 
addition, there are "slots" pre-allocated for than in the data subfile. 
In other words, each record will get put in the proper slot according 
to its assigned record nunber. 



Sequential Record Aidition 

In SEQUENTIAL access mode, the file must be opened for OUTPUT, not I-O, 
as mentioned previously in the note following (Usening and Qosing the 
File . The other restriction on sequential record addition is that once 
the file contains entries, you can't add records to it in SEQUENTIAL 
mode: you must use RANDOM or DYNAMIC access mode. In SEQUENTIAL 
access mode, the user does not supply record nunbers for each entry 
added, but instead lets CCBOL take care of providing a unique number 
for each record. CCBOL always starts nunbering with the lowest 
possible nunber in the sequence which happens to be 000001, if the 
RELATIVE KEY is declared as 6 characters (48 bits) , arxS is incremented 
by 1 each time a new record is added. Although it's not illegal for 
the user to provide record nunbers during sequential record addition 
they are ignored by CCBOL anyway. In fact, if the RELATIVE KEY field 
is defined by the user in the program (this is not required, as 
mentioned above), CCBOL will return, in the RELATIVE KEY field, the 
record nunber of each record you add after each WRITE operation is 
complete . 



11 - 13 October 1980 



SECTICN 11 IDR4558 



NDte 



Follow this rule v*ien adding records to a RELATIVE file: once 
a file contains entries, v*iether they were added sequentially 
or randomly, the file should not be opened for SEQUENTIAL 
OUTPUT. Dfew records can only be added to the file if it is 
opened for DYNAMIC or RANDCM access. 

The format of the WRITE statanent is: 

WRITE record-name [FROM new-record] 
[INVALID KEY imperative-statement]. 

record-name is the name of a record description associated with the 
file m the DATA DIVISION of the program. The "FRCM new-record" clause 
is optional; without it, the user must explicitly MOVE the new record 
information to record-name so it can be written to the file. 

For Example ; The example below shows how records can be added 
interactively to a RELATIVE file. (User input is underlined to 
distinguish it from program output.) 

ID DIVISION. 

mOGRAM-ID. ADD-reOG. 

AUTHOR. UD. 

INSTALLATION. TPUBS. 

DATE-WRITTEN. 09/02/80. 

DATE-COMPILED. 09/02/80. 

SECURITY. NONE. 

REMARKS. PROGRAM TO TEST DACUST FILE ADDS. 

ENVIR0I*1ENT DIVISION. 

CCNFIGURATIC^I SECTION. 

SOURCE COMPUTER. PRIME. 

OBJECT COMPUTER. PRIME. 

INPlfT-OUTPUT SECTION. 

FILE-CONTROL. 

SELECT DACUST ASSIGN TO PFMS 
ORGANIZATION IS RELATIVE 
ACCESS MODE IS SEQUENTIAL 
RELATIVE KEY IS RECORD-NO 
FILE STATUS IS STATUS-CODE. 
DATA DIVISION. 
FILE SECTION. 
FD DACUST 

LABEL RECORDS ARE STANDARD 

VALUE OF FILE-ID IS " DACUST' 

DATA RECORD IS CUST-FILE-RECORD. 
01 CUST-FILE-RECORD. 

02 CUST-ID PIC X(5) . 

02 CUST-NAME PIC X(25) . 

02 LOCATION-CODE PIC X(4) . 

02 FILLER PIC X(35) . 
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WORKING-STORAGE SECTION. 

01 STATUS-CODE PIC 99 VALUE ZERO. 

01 READ=RBC PIC X{35) VALUE SPACES. 

01 RECORD-NO PIC 9(6) VALUE ZEROES. 

PROCEDURE DIVISION. 

FIRST-PROC. 

OPEN OUTPUT EACUST. 
GET-DATA. 

DISPLAY 'ENTER DACUST ID - - PIC X(5) OR ENTER XX TO QUIT' . 
ACCEPT CUST-ID. 
IF CUST-ID = 'XX' GO TO FINIS. 
GET-REST. 

DISPLAY ' ENTER CUST-NAME — 25 CHARS' . 
ACCEPT CUST-NME. 

DISPLAY 'ENTER LOCATION COIM — 4 CHARS (REGION-STATE)'. 
ACCEPT LOCATION-CODE. 

WRITE CUST-FILE-RECORD INVALID KEY GO TO CHECK. 
GO TO GET-DATA. 
CHECK. 

IF STATUS-CODE NOT = 00 DISPLAY ' RECCM) NOT ADDED' 
ELSE GO TO GET-REST. 
GO TO GET-DATA. 
FINIS. 

IF STATUS-CODE = 00 DISPLAY 'ALL DONE' 
ELSE 

UXOfUKl "DlftlUO V-UJJEi Lot' Diftiub— UUl-'D. 

CLOSE DACUST. 
STOP RUN. 



ok, seg #add.da 

ENTER FILE ASSIGWENTS: 

> / 

FILE ASSIGNMENTS CCMPLETE. 

ENTER DACUST ID PIC X(5) OR ENTER XX TO QUIT 

4456P 

ENTER CUST-NAME — 25 CHARS 

LESLEY'S PASTE-UP SHOP 

ENTER LOCATION CODE ~ 4 CHARS (REGIOJ-STATE) 

NEMA 

ENTER DACUST ID - - PIC X(5) OR ENTER XX TO QUIT 

3378T 

ENTER CUST-NAME —25 CHARS 

AUTOMAT TYPESETTERS 

ENTER LOCATION COOE ~ 4 CHARS (REGION-STATE) 

MWID 

ENTER DACUST ID - - PIC X(5) OR ENTER XX TO QUIT 

XX 

ALL DONE 

When read back sequentially, the records will be returned in the order 
added. See Reading Sequentially, below. 
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Note 



START operations are not legal in RELATIVE files opened for 
SEQUENTIAL access in OUTPUT mode — so there's no way to start 
adding records at any point in the file other than the 
beginning of the file. 



Adding Records Randonly 

In randcxn writes, the user must supply a record nunber for each record 
added. Ihe format is the same as that shown for sequential reads, 
above. The file can be opened for OUTPUT or I-O. 

Example ; This program opens a file for 1-0 in DYNAMIC access mode and 
does randcxn, interactive adds. Naturally, records can be added by 
reading in the data from another disk file as well, but a record nunber 
must be supplied with each record added. The important thing to note 
about adding records randomly is that record nunbers must be supplied 
in the proper form — don't forget those leading zeroes! 

ID DIVISION. 

PROGRAM-ID. ADD-PROG. 

AUTHOR. LJD. 

INSTALLATICW. TPUBS. 

DATE-WRITTEN. 09/02/80. 

DATE-CCMPILED. 09/02/80. 

SECURITY. NONE. 

REMARKS. PROCa^AM TO TEST DACUST FILE WRITES. 

ENVIR0M>1ENT DIVISICM. 

C(*IFIGURATION SECTIC»J. 

SOURCE COMPUTER. PRIME. 

CBJECT COMPUTER. PRIME. 

INPUT-OUTPUT SECTION. 

FILE-CONTROL. 

SELECT DACUST ASSIGN TO PFMS 
ORGANIZATION IS RELATIVE 
ACCESS MODE IS DYNAMIC 
RELATIVE KEY IS RECCHD-NO 
FILE STATUS IS STATUS-CODE. 
DATA DIVISION. 
FILE SECTICSJ. 
FD DACUST 

LABEL RECORDS ARE STANDARD 

VALUE OF FILE-ID IS "DACUST" 

DATA RECORD IS CUST-FILE-RECORD. 
01 CUST-FILE-RECCRD. 

02 CUST-ID PIC X(5) . 

02 CUST-NAME PIC X(25) . 

02 LOCATION-CODE PIC X{4) . 

02 FILLER PIC X(35) . 
WORKING-STORAGE SECTION. 
01 STATUS-CODE PIC 99 VALUE ZERO. 
01 READ-REC PIC X(35) VALUE SPACES. 
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01 RECCM)-NO PIC 9(6) VALUE ZEROES. 

PRCCEWJRE DIVISION. 

FIRST-PROC. 

OPEN OUTPUT EACUST. 
GET-DATA. 

DISPLAY • ENTER RECCED NUMBER' . 
ACCEPT RECCRD-NO. 
DISPLAY 'ENTER DACUST ID - - PIC X{5) OR ENTER XX TO QUIT'. 
ACCEPT CUST-ID. 
IF CUST-ID = 'XX' GO TO FINIS. 
GET-REST. 

DISPLAY • ENTER CUST-NAME — 25 CHARS' . 
ACCEPT CUST-NAME. 

DISPLAY 'ENTER LOCATION CODE — 4 CHARS (REGION-STATE) ' . 
ACCEPT LOCATION-CODE. 

WRITE CUST-FILE-RECCI® INVALID KEY GO TO FINIS. 
GO TO GET-DATA. 
FINIS. 

IF STATUS-CODE = 00 DISPLAY "ALL DONE' 

ELSE 
DISPLAY 'STATUS CODE IS:' STATUS-CODE. 
CLOSE DACUST. 
STOP RUN. 
OK, 

Some sample input to the program might be (user input is underlined) : 

ENTER RECCM3 NUMBER 
000005 

ENTER EftCUST ID PIC X(5) OR ENTER XX TO QUIT 

5556X 

ENTER CUST-NAME — 25 CHARS 

MISCELLANEOUS SUPPLIERS 

ENTER LOCATION CODE — 4 CHARS (REGICW-STATE) 

SEGA 

ENTER RECORD NUMBER 

000006 

ENTER DACUST ID - - PIC X(5) OR ENTER XX TO QUIT 

5556A 

ENTER CUST-NAME — 25 CHARS 

ROCKY POINT ART SHOP 

ENTER LOCATION CODE ~ 4 CHARS (REGION-STATE) 

NENY 

etc. 

You can add entries in any order. Don't try to write a record that 
already exists and don't try to write beyond the pre-allocated file 
boundaries. If you only allocated 15 records, then don't try to add a 
record with niinber 000016 or above. Remember that CREATK asks for a 
number of records for v*iich to allocate space for in an index subfile. 
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READING A RELATIVE FILE 



Ihere are tWD types of READ fomats for RELATIVE files: the sequential 
read format and the random read format. The formats are similar to 
those used in reading INDEXED SEQUENTIAL files. 



Sequential Reads 

In a direct access file opened for SEQUENTIAL access, the READ 
operation retrieves records in order by record nunber. The initial 
record nunber value with v*iich to begin is established by a MOVE and 
START, by setting an initial value in WORKING STORAGE, or by default, 
in vhich the initial position is set to the first record in the file. 
The first file record by definition has the lowest record number in the 
entire file. Sequential REAEs are generally associated with SEQUENTIAL 
access mode, although they are possible in DYNAMIC mode also. 

The READ statement format used for sequential retrieval is: 

READ filename [NEXT RECORD] [INTO read-var] 
[AT END imperative-statement] . 

filename is the name of the RELATIVE file. The "INTO read-var" clause 
causes the record read to be moved from the record buffer associated 
with the file into the read-var variable. The NEXT clause is used only 
in DYNAMIC access mode; it is not necessary if the file is opened for 
SEQUENTIAL access mode because a READ operation automatically causes 
the file pointer to move to the next record in the file. The "AT END^ 
clause is required unless there is a USE AFTER procedure under the 
DECLARATIVES for handling errors that occur v*iile processing the file. 

Example ; Ihe following program reads values from a RELATIVE file 
sequentially by record nunber. NDte that the file is opened for INPUT, 
Vthich means that the file is opened for reading only, as opposed to 
writing and/or update. 

ID DIVISION. 

PROGRAM-ID. DACUST-TST. 

AUTHOR. LJD. 

INSTALLATION. TPUBS. 

DATE-WRITTEN. 09/02/80. 

DATE-COMPILED. 09/02/80. 

SECURITY. NONE. 

REMARKS. PROGRAM TO TEST DACUST FILE REAES. 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE COMPUTER. PRIME. 

OBJECT COMPUTER. PRIME. 

INPUT-OUTPUT SECTION. 

FILE-CONTROL. 

SELECT DACUST ASSIGN TO PFMS 

ORGANIZATION IS RELATIVE 

ACCESS MODE IS SEQUENTIAL 
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RELATIVE KEY IS RBCCFD-NO 
FILE STATUS IS STATUS-CODE. 
DATA DIVISION, 
FILE SECTION. 
FD DACUST 

LABEL RECORDS ARE STANDARD 
VALUE OF FILE-ID IS "DACUST* 
DATA RECORD IS CUST-FILE-RECO^. 
01 CUST-FILE-RECCRD. 

02 CUST-ID PIC X(5) . 

02 CUST-NAME PIC X{25) . 

02 LOCATION-CODE. 

05 REGION PIC XX. 
05 STATE PIC XX. 
WORKING-STORAGE SECTION. 
01 STATUS-CODE PIC 99 VALUE ZERO. 
01 RECCM>-NO PIC 9(6) VALUE ZEROES. 
01 READ-REC PIC X(35) VALUE SPACES. 
mOCEDURE DIVISION. 
FIRST-PROC. 

OPEN INPUT DACUST. 
MOVE LOW-VALUES TO RECCM>-NO. 

START DACUST KEY IS NOT LESS THAN RECORD-NO INVALID KEY 
GO TO END-FILE. 

REAE^LOOP. 

Diran narncT xKFnn DPan_Di?r' at irMn nn tv-i c\TTv.irTT c 

DISPLAY 'RECORD NO. IS:' RECCBD-NO. 
DISPLAY READ-REC. 
GO TO READ-LOOP. 
END-FILE. 

CLOSE DACUST. 

IF STATUS-CODE =00 DISPLAY 'SUCCESSFUL COMPLETIdJ. ' 

ELSE 

DISPLAY 'STATUS CODE IS:' STATOS-CODE. 

STOP RUN. 

When run, the program output is: 

RECORD NO. IS: 000001 

C4456PLESLEY' S PASTE-UP SHOP NET1A 

RECORD NO. IS: 000002 

3378TAUTCMAT TYPESETTERS MWID 

SUCCESSFUL COMPLETIOJ. 

OK, 

Reading the Current Itecord : In DYNAMIC access mode, READ without the 
KEY IS or NEXT RECORD clauses returns the current record . In RANDOM 
access mode, READ without the KEY IS clause also returns the current 
record. (Remember that sequential reads are not possible in RANDOM 
mode.) current record is the one just read or positioned to by a STPRT 
operation (START is not legal in RANDOM access) . In SEQUENTIAL access 
mode, the file pointer is advanced automatically to the next record in 
the file each time a READ statement is encountered . 
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Keyed Reads 

Keyed reads (randan reads) are permitted in UitiMlC and RANDCM access 
modes, using the RELATIVE KEY. lb do a keyed read, simply MOVE the 
appropriate record number value to the RELATIVE KEY field, then use 
this form of the READ statement: 

READ filename [INTO read-var] 
[INVALID KEY imperative-statQonent] . 

The " INTO read-var " option is used to move the data record f rc«n the 
buffer into v*iich it is read to some progran-specified temporary 
storage area (naned by read-var ) so the user can do scanething with it 
like DISPLAY, for instance. The INVALID KEY clause is required unless 
a USE AFTER procedure urrfer the DECLARATIVES specifies v*iat to do v*ien 
errors occur during processing of that file. 

This format requires that a new value be moved to the RELATIVE KEY 
field before each READ, or the same record will be returned over and 
over again. Remember, the only way to do a keyed READ on a RELATIVE 
file is to supply a record nunber value for the RELATIVE KEY field. 

Ksyed READ Biample ; Ihe following example shows an excerpt from a 
program that does randan READs on the DACUST file. 

PROCEDURE DIVISION. 
FIRST-PROC. 

OPEN INPUT DACUST. 
MOVE 000002 TO RECORD-NO. 
REAE^RANDCM. 

READ DACUST INTO READ-REC 
INVALID KEY GO TO KEY-ERR. 
DISPLAY 'RECORD NUMBER IS:' RECORD-NO. 
DISPLAY READ-REC. 
READ-CUR. 

READ DACUST INTO READ-REC 

INVALID KEY GO TO KEY-ERR. 
DISPLAY 'KEY FIELD NOT UPDATED:' . 
DISPLAY ' READ RETURNS CURRECT RECCRD. ' . 
DISPLAY READ-REC. 
GO TO FINIS. 
KEY-ERR. 

DISPLAY 'STATUS CODE IS:' STATUS-CODE. 
FINIS. 

IF STATUS-CODE =00 DISPLAY 'ALL DONE' . 
CLOSE DACUST. 
STOP RUN. 
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When run, the program prints the following: 

RECCBD NIWBH? IS: 000002 

3378TAUT0MAT TYPESETTERS MWID 

KEY FIELD NOT UPDATED: 

READ RETURNS CURRENT RECORD. 

3378TAUrCMAT TYPESETTERS MWID 

ALL DONE 

OK, 

Reading the Current Record ; In DYNAMIC arxJ RANDOM access modes, if the 
RELATIVE KEY field is not updated between the last READ or START and 
the current READ, a READ without the NEXT RECORD clause will return the 
current record; that is, the record just read or positioned to by a 
START operation. See the above example. 



UPDATING RECORDS 

The REWRITE statement simply replaces the current record with a new 
text string, completely destroying the original. It's essential to 
remember that REWRITE does not establish or alter file position: 
therefore, you must do a READ before a REWRITE in order to tell MIDftS 
vibich record is to be updated and to lock the record. This is true in 
all access modes. Ranember also that the file must be opened for I-O 
in order to update it. 

Ihe REWRITE format is: 

REWRITE record-name [FROM new-record] 
[INVALID KEY imperative-statement]. 

record-name is the name of a record associated with a file described in 
the File Description under the File Section of the program. The "FROM 
new-record" clause is optional because you can alvays move the new 
record value to record-name before you do the REJ«/RITE. The INVALID KEY 
clause is mandatory in RANDOM and DYNAMIC modes, unless the 
DECLARATIVES includes a USE AFTER procedure for dealing with errors 
that occur viiile processing this file. The INVALID KEY clause should 
not be included in REWRITE statanents vAien the file is opened for 
SEQUENTIAL access. 

Example : Ihis program opens the DACUST file for DYNAMIC access and 
updates an existing record: 

ID DIVISION. 

reOGRAM-ID. UPDATES. 

AUTHOR. LJD. 

INSTALLATION. TPUBS. 

DATE-WRITTEN. 09/02/80. 

DATE-COMPILED. 09/02/80. 

SECURITY. NONE. 

REMARKS. PROGRAM TO TEST Di^CUST FILE UPDATES. 
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ENVIRONMENT DIVISION. 
CONFIGURATION SECTIC»I. 
SOURCE COMPUTER. PRIME. 
CBJECT COMPUTER. HIIME. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT EACUST ASSIGN TO PFMS 
ORGANIZATION IS RELATIVE 
ACCESS MODE IS DYNAMIC 
RELATIVE KEY IS RECORD-NO 
FILE STATUS IS STATUS-CODE. 
DATA DIVISION. 
FILE SECTIOI. 
FD DACUST 

LABEL RECORDS ARE STANDARD 
VALUE OF FILE-ID IS "DACUST' 
DATA RECORD IS CUST-FILE-RECORD. 
01 CUST-FILE-RECCHD. 

02 CUST-ID PIC X(5) . 

02 CUST-NAME PIC X(25) . 

02 LOCATION-CODE. 

05 REGION PIC XX. 

05 STATE PIC XX. 

WORKING-STORAGE SECTION. 
01 STATUS-CODE PIC 99 VALUE ZERO. 
01 READ-RBC PIC X(35) VALUE SPACES. 
01 RECORD-NO PIC 9(6) VALUE ZEROES. 
01 NEW-RECORD PIC X(35) VALUE SPACES. 
PROCEDURE DIVISION. 
FIRST-PROC. 

OPEN I-O DACUST. 
MOVE 000001 TO RECOyD-NO. 
READ-THIS. 

READ DACUST INTO READ-REC 

INVALID KEY GO TO KEY-ERR. 
DISPLAY 'CURRENT RECORD IS:' READ-REC. 
CHANGE-VAL. 

MOVE ' 2334PSEACOAST FINISHERS WRCA' TO NEW-RECORD. 

UPDATE. 

REWRITE CUST-FILE-RECORD FROM NEW-RECOUD 

INVALID KEY GO TO KEY-ERR. 

READ DACUST INTO READ-REC INVALID KEY 

GO TO KEY-ERR. 
DISPLAY 'UPDATED RECORD IS:' READ-REC. 
GO TO FINIS. 
KEY-ERR. 

DISPLAY 'STATUS CODE IS:' STATUS-CODE. 
FINIS. 

IF STATUS-CODE = 00 DISPLAY 'ALL DONE' 
ELSE DISPLAY 'STATUS CODE IS:' STATUS-CODE. 
CLOSE DACUST. 
STOP RUN. 
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OK, seg #up.da 

ENTER FILE ASSIGNMENTS: 

N. / 
-' f_ 

FILE ASSIGNMENTS CCMPLETE. 

CURRENT RECCM) IS:4456PLESLEY'S PASTE-UP SHOP NEMA 
UPDATED RECC«D IS:2334PSEACOAST FINISHERS WRCA 
ALL DOIE 
OK, 



DELETING RECORDS 

The DELETE statement removes an indicated record from a direct access 
file. Deletes can be done in any access mode: RANDOM, DYNAMIC or 
SEQUENTIAL, but the file must be opened for I-O in all cases. Ihe 
DELETE format is: 

DELETE filename RECORD [INVALID KEY imperative-statement] . 

In RANDW and DYNAMIC modes the INVALID KEY clause must be used unless 
a USE AFTER procedure for trapping errors is included under the 
DECLARATIVES. The INVALID KEY clause is not legal in SEQUENTIAL access 
mode because the record to be deleted is established by a READ and not 
by the DELETE operation itself. 



Deletes in SEQUENTIAL Mode 

In SEQUENTIAL access mode the record to be deleted must be READ before 
a DELETE can be executed. "Ihis is because the DELETE statement in 
SEQUENTIAL acess mode cannot establish a current record position and 
must instead depend on a READ to do so. The INVALID KEY clause should 
not be included in the DELETE statement \n*ien the file is opened for 
SEQUENTIAL access. 



Deletes in DYNAMIC and RANDOM Modes 

In DYNAMIC and RANDOM access modes, it is not necessary to do a READ 
prior to a DELETE because a DELETE establishes the current record 
position on its own. The user must supply a value for the RELATIVE KEY 
before a DELETE vrfiich is then used to position to that record before 
deleting it. 



DELETE Examples 

The first program excerpt shown below is frcan a program in vrfiich a 
RELATI\^ file has been opened for 1-0 in SEQUES^TIAL access mode. In 
order to delete a record from this file, the record nunber must be 
M0VE3 to the RELATIVE KEY field, then read, and then deleted: 
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PROCEDURE DIVISION. 
FIRST-reOC. 

OPEN I-O DACUST. 

MOVE 000001 TO RECCMD-NO. 

START DACUST KEY IS NOT LESS THAN RECORD-NO INVALID KEY 

GO TO KEY-ERR. 
READ DACUST INTO READ-REC AT END GO TO FINIS. 
DISPLAY READ-REC. 
DEL-REC. 

DELETE DACUST. 

Ttie program prints out the record to be deleted just before the DELETE 
statanent is actually executed. If you want to keep track of the 
records being deleted from a file, opening the file in SEQUENTIAL 
access mode forces you to read each record first, v*iich makes it easy 
to keep an "audit file" of the records deleted. 

When a RELATIVE file is opened for DYNAMIC access, the record to be 
deleted does not have to be read first and no START statement is 
required either, as this program excerpt shows: 

PROCEDURE DIVISICXl. 
FIRST-FROC. 

OPEN 1-0 DACUST. 
MOVE 000002 TO RECCFID-NO. 
DEL-REC. 

DELETE DACUST INVALID KEY GO TO KEY-ERR. 
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INTRODUCTION 

MIDAS file maintenance generally involves monitoring MIDAS file index 
subfile and data subfile usage, and making minor adjustments to 
increase file efficiency. Maintenance also involves the periodic 
restructuring of the index subfiles and the data subfile with the MPACK 
utility to reclaim space "wasted" by data entries and index subfile 
entries v^tiich have been marked for deletion. Occasionally, records in 
the data subfile may become locked during use due to program abort or 
error, and the MPACK utility must be run to unlock these records. 

Ihis section discusses the CREATK options which can be used to monitor 
MIDAS file use and size, and the MPACK utility which can help you 
maintain an efficiently organized MIDAS file. 



EXAMINING THE TEMPLATE 

CREATK has other uses besides tenplate creation. This section 
discusses the PRINT, USAGE, SIZE and VERSION options of CREATK. CREATK 
calls than "functions" — we use functions and options interchangeably 
in referring to them. These functions provide details on file size, 
template structure, index usage and can estimate the nimber of 
segements needed, given a hypothetical number of entries for a data 
subfile. The CREATK options which can be used to modify a file are 
dealt with in Section 14. 



Option Sjnmary 

To examine an existing file template, enter CREATK, provide the file's 
name or pathname v*en requested, and enter "no" to the "NEW FILE?" 
prompt as indicated in the example below. CREATK then prcmpts you to 
enter a function in response to the "FUNCTICK?" pranpt. Tb obtain a 
complete list of options, type "HELP". A list of functions and a brief 
description of each one is then displayed. Minimum abbreviations for 
each function are indicated with brackets; the portion enclosed in 
brackets is optional. 
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OK, creatk 
[CREATK rev 17.6] 

MINIMUM OPTICUS? yes 

FILE NAME? custcmer 
NEW FILE? no 



FUNCTICM? help 
A[DD] 
D[ATA] 
EtXTEND] 
F[ILE] 
H[ELP] 
M[ODIFY] 
P[RINT] 
Q[UIT] 
(C/R) 
S[IZE] 
U[SAGE] 
V[ERSION] = 



ADD AN INDEX 

CHANGE DATA RECORD SIZE 

CHANGE SEGMENT & SEGMENT DIRECTORY LENGTH 

OPEN A NEW FILE 

PRINT THIS SUMMARY 

MODIFY AN EXISTING SUBFILE 

PRINT DESCRIPTOR INFORMATION 

EXIT CREATK 

IMPLIED QUIT 

DETERMINE THE SIZE OF A FILE 

DISPLAY CURRENT INDEX USAGE 

MIEAS DEFAULTS FOR THIS FILE 



The options available for examining the template are: 

PRINT Prints description of various index structures. 

USAGE Displays number of entries in each index and the version 
~ of MIDAS last used to modify the file. 

SIZE Estimates number of segments and disk records needed to 
"~ acccmmodate a given number of data file entries. 

VERSION Displays version of MIDAS used to create file. 

The minimiin abbreviation for each option is underlined. The function 
of each option is expanded upon in the following paragrafiis. 



The PRINT Cation 

PRINT displays index and data subfile information, 
prompts for an index subfile number with this prompt: 

INDEX NO? 



It automatically 



Enter a nunber fran to 17 if you want to see information on a 
particular index subfile. Ehter the word "DATA" to examine data 
subfile information. 
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If an index subfile is being examined, CREATK displays: 

• Number of segments allocated 

• Index capacity ( approximate nunber of entries that can be 
acconmodated) 

• Key type and size 

• Number of index levels as of last MPACK. 

For each index level in a particular index si±)file, the PRINT option of 
CREATK displays this information: 

• Block size (number of words per block) 

• Key length 

• Number of control wards 

• Maximun nunber of entries per block 

• length of an index entry 

• Number of blocks in that level 

For Example ; The next example shows how reiNT (abbreviated "p") can 
be used to obtain information about all of the indexes in a MIEAS file. 
In this case, the statistics shown pertain to the CUSTOMER file. Nate 
that the size for character type keys is displayed in both words and 
bytes. Since there is only one level of indexing for this file, (it 
contains only 5 entries) statistics are displayed for the "last level" 
of indexing only. In order to obtain the latest information on a 
file's index levels and number of blocks at each level, the file must 
have been MPACIfed after the latest rourxJ of changes made to the file. 
See Section 15, Index Levels , for details on levels of indexing in the 
subfiles. 
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FUNCTION? print 

INDEX NO.? 

10 SEGMENTS ALLOCATED WHICH CAN HOLD ABOUT 774144. ENTRIES 

KEY TYPE: CHARACTER 

KEY SIZE 5 BYTES ( 3 WORDS) 

# LEVELS: 1 SYNONYM ENTRIES NOT SUPPORTED 

LAST LEVEL 

ENTRY SIZE: 6 WORDS BLOCK SIZE: 1024 WORDS # COJTROL WORDS: 10 
MAX ENTRIES/BLOCK: 169 # BLOCKS THIS LEVEL: 1. 



FUNCTION? p 

INDEX NO.? i 

10 SEGMENTS ALLOCATED WHICH CAN HOLD ABOUT 285696. ENTRIES 

KEY TYPE: CHARACTER 

KEY SIZE 25 BYTES ( 13 WORDS) 

# LEVELS: 1 SYNONYM ENTRIES SUPPORTED 

LAST LEVEL 

ENTRY SIZE: 16 WORDS BLOCK SIZE: 1024 WORDS # COJTROL WORDS: 10 
MAX ENTRIES/BLOCK: 63 # BLOCKS THIS LEVEL: 1. 



FUNCTION? p 

INDEX NO.? 2 

10 SEGMENTS ALLOCATED WHICH CAN HOLD ABOUT 926231. ENTRIES 

KEY TYPE: CHARACTER 

KEY SIZE 4 BYTES ( 2 WORDS) 

# LEVELS: 1 SYNONYM ENTRIES SUPPORTED 

LAST LEVEL 

ENTRY SIZE: 5 WORDS BLOCK SIZE: 1024 WORDS # CONTROL WORDS: 10 
MAX ENTRIES/BLOCK: 202 # BLOCKS THIS LEVEL: 1. 
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If the "data" option is specified, CREATK displays: 

• Number of index subfiles defined 

• Number of entries currently indexed as of last MPACK 

• Eh try size (record size) 

• Primary key size 

FUNCTICK? £ 

INDEX NO.? d ("d" for data) 
DATA SUBFILE: 

FILE TYPE: KI # INDEXES: 3 # ENTRIES: 0. 

ENTOY SIZE 35 WOUDS 

PRIMARY KEY SIZE: 5 BYTES ( 3 WC3RDS) 

NDte that the DATA option returns the file configuration (FILE TYPE:) 
as either KI (keyed-index) or Dft (direct access) . 

The SIZE Option 

The SIZE option determines the number of segments and disk records 
required for an index subfile, a data subfile, or an entire file, given 
a projected number of records for a MIDAS file. The user supplies the 
number of records in response to this prompt: 

NUMBER OF ENTRIES: 
CREATK then asks for an index number : 

INDEX NO: 
to viiich the user should respond with one of the following : 

• A number from 0-17 — obtain estimate for an individual index 
subfile 

• DATA — obtain an estimate for a data subfile 

• TOTAL — obtain an estimate for the entire file, including all 
index subfiles and data subfiles 

• {CR) — terminates the SIZE option dialog and returns you to the 
"FUNCTIOJ?" prompt. 
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If the user specifies an index number or the DATA option, CREATK 
returns the following: 

• Number of disk records needed for the index or data subfile 

• Nuniber of segments required to contain these index blocks 

• Number of segments currently allocated for the index blocks 
already in the index or data subfile 

FUNCTION? size 

NUMBER OF ENTRIES: 400 (try 400 records ) 

INDEX NO.? 

INDEX 0: 8 440 WD. RECS, 5 1024 WD. RECS 
2 SEGMENTS REQUIRED, 10 SEGMENTS ALLOCATED 

INDEX NO.? 1 

INDEX 1: 18 440 WD. RECS, 9 1024 WD. RECS 
2 SEGMENTS REQUIRED, 10 SEOIENTS ALLOCATED 

INDEX NO.? 2 

INDEX 2: 7 440 WD. RECS, 4 1024 WD. RECS 
2 SEGMENTS REQUIRED, 10 SEGMENTS ALLOCATED 

INDEX NO.? data 

DATA : 37 440 WD. RECS, 16 1024 WD. RECS 
1 SEGMENTS REQUIRED, 327 SEGMENTS ALLOCATED 

INDEX NO.? (CR) 

Should the MIDAS file have variable length records, you'll get this 
message v^en you use the "data" option: 

VARIABLE LENGTH n?^TA, NO COMPUTATION 

If the TOTAL option is specified in response to the INDEX NO.? prompt, 
CREATK prints all the above information for each index subfile and the 
data file plus the number of disk blocks needed to accommodate all 
index subfiles and the data subfile. Fbr example: 

FUNCTICN? size 

NUMBER OF ENTRIES: 2000 

INDEX NO.? total 

INDEX 0: 30 440 WD. RECS, 14 1024 WD. RECS 

2 SEOIENTS REQUIRED, 10 SEGMENTS ALLOCATED 
INDEX 1: 78 440 WD. RECS, 35 1024 WD. RECS 

2 SEGMENTS REQUIRED, 10 SEGMENTS ALLOCATED 
INDEX 2: 26 440 WD. RECS, 12 1024 WD. RECS 

2 SEQ1ENTS REQUIRED, 10 SEGMENTS ALLOCATED 
DATA : 182 440 WD. RECS, 79 1024 WD. RECS 
1 SE01ENTS REQUIRED, 327 SEGMENTS ALLOCATED 

TOTAL DISK RECORDS: 316 440 WD. RECS, 140 1024 WD. RECS 
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The iiqar:i? nDH^i-i 

The USAGE option helps detennine how many entries you've got in each 
index subfile. It displays the following information: 

• Eata records indexed as of last MPACK 

• Data records added since last MPACK 

• Data records deleted since last MPACK 

• Tbtal number of data records (entries) in the file 

• The version of MIDAS v*ich last modified the file 

Ihis example shows how many entries are currently in the primary and 
secondary index subfiles of a certain MIDAS file: 

FUNCTIC»J? usage 
INDEX? 

ENTRIES INSERTED: 
ENTRIES DELETED: 2 
TOTAL ENTRIES IN FILE: 5 

LAST MODIFIED BY MIDAS REV. 17.6 

FUNCTICN? u 

INDEX? 1 

ENTRIES INDEXED: 7 
ENTRIES INSERTED: 

ENTRIES DELETED: 
TOTAL ENTRIES IN FILE: 7 

LAST MODIFIED BY MIDAS REV. 17.6 

FUNCTICK? u 

INDEX? 2 

ENTRIES INDEXED: 7 
ENTRIES INSERTED: 
ENTRIES EffiLETED: 
TOTAL ENTRIES IN FILE: 7 

LAST MODIFIED BY MIDAS REV. 17.6 
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The VERSION Option 

The VERSION option displays the following infonnation: 

• The version of KIDALB (the MIDAS library) which was used in 
building the tonplate 

• Ihe default DAM file length (524288 words) 

• The default segment directory length (512 segments) 

• Maximun segments allocated per index (10) 

• The maximum nunber of indexes (including the primary) which can 
be defined for the file (18) 

FUNCTIC»1? V 
[CREATE rev 17.6] 

FILE CREATED BY KIDAIB REV. 17.6 

DEFAULT PARAMETERS FOR FILE 

Dm FILE LENGTH 524288 WORDS 

BASIC SEGMENT DIRBCTCHY LENGTH 512 SEGMENTS 

MAXIMUM SEGMENTS PER INDEX 10 

MAXIMUM NUMBER OF INDEXES 18 

When debugging MIDAS applications, remember to check the version of 
MIDAS you're using — it may help you to pinpoint the problan. 



THE MPACK UTILITY 

V&\en you delete an index subfile entry, MIDAS automatically recovers 
the space formerly occupied by that entry. However, this is not the 
case for data subfile records: they are marked for deletion but are 
not F*iysically removed until the MPACK utility is run. MPACK' s chief 
function is to recover the space occupied by data records marked for 
deletion, freeing that space for additional records and increasing file 
efficiency — but it does a lot of other things as well, like unlocking 
locked records and restructuring index subfiles. 

Note 

When making changes to the tanplate structure with the ADD, 
DATA, EXTEND and MODIFY options of CREATK (covered in Section 
14) , you must MPACK the file after you've specified the 
changes. The desired modifications do not take effect until 
MPACK is executed on the file. 
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MPACK's Functions and Options 

MPACK's specific fanctions are surrmarized below: 

• Reclamation of space occupied by "deleted" data records 

• Packing up of indexes to minimize disk space used 

• Unlocking of all data records left locked after program abort or 
failure 

• Reordering the data subfile to match the order of primary index 
subfile entries (complete file restructure) 

• togging errors and milestones to keep tabs on errors and to 
monitor the ongoing operation 

Milestone/Error Logging ; MPACK allows you to open an error/log file 
to keep track of any errors that occur during unlock or MPACK; in 
addition, an optional milestone status report can be recorded for a 
given number of records processed by MPACK. Ihe milestone count is a 
user-specified number. The milestone statistics include date, time (in 
24-hr. format), CPU and disk time used and the time expired between 
the current milestone and the previous one. For an example of a 
milestone event, see the sample output at the end of this section. 



THE MPACK DIALOG 

The MPACK dialog offers you two basic choices: 

• You can restructure the file 

or 

• You can simply unlock the locked file entries 

lb restructure index subfiles or the entire file, use the MPACK option, 
optionally abbreviated to M. The MPACK option then asks v*iat part of 
the file is to be restructured. Ihese options are described below. Td 
perform the unlock operation, type UNLOCK or U. 

The UNLOCK Option 

Ihe UNLOCK option simply goes throigh the data subfile entries looking 
for locked records. All locked records are unlocked and MPACK prints 
out a total coimt of imlocked records. Ihe index subfiles are not 
touched during the "UNLOCK" option path. 
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The Restructure Option (MPACK) 

The "MPACK" option path lets you restructure one or more index 
subfiles, all of the index subfiles, or the entire file. During an 
index restructure operation, MPACK searches the index subfile entries 
for entries that have been marked for deletion or for entries that are 
out of order. If any keys are out of sequence, MPACK reports them to 
the user, but does not reorder than. Secondary index entries vhich 
point to data subfile entries v*iich have been marked for deletion are 
deleted so their space can be re-used. 

In a data subfile restructure, the entries are reordered to correspond 
to the primary index order, and space wasted by "deleted" records is 
reclaimed for use. ^ce in the data subfile is reclaimed by copying 
the old data subfiles to new ones. At the end of the MPACK run, the 
old subfiles are deleted ahd the new ones replace them. Because of 
this copying procedure, the user must make sure that MPACK has enough 
disk space to make a copy of the original file being MPACked. 

Quickly sutrmarized, the restructure options are: 

• The index-number option: you simply specify vAiich individual 
index subfiles are to be restructured. 

• The DATA option: restructures the data subfile and all indexes. 

• The ALL option: reclaims wasted space from all the index 
subfiles. 

The DATA Sub-option ; "lb restructure the entire file, use the DATA 
option. The chief benefit of the LATA option is that it not only 
checks and reorders the index subfile entries, but it also reorders the 
data subfile entries to correspond to the order of key entries in the 
primary index subfile and recovers data subfile spaces. In other 
words, it sorts the data subfile by primary key, using the key order in 
the primary index subfile. This makes sequential file processing a lot 
faster and makes key searches more efficient. 

If the DATA option is specified, MPACK then asks if you want to 
overwrite the existing file or make a copy and work on that. 

It is highly recommended that you always say NO to the "OK TO 
OVEFiWRITE?" query. This ensures that you will always have a copy of 
the original file in case you need it. In this case, MPACK asks you to 
specify the name of a file to which you want the restructured file to 
be written. The original file will be left intact and all the changes 
will be made to a copy of the file. If you accidentally specify the 
name of an existing file, (MIDAS or non-MIDAS) , MPACK will display a 
message like: 

FILENAME ALREADY EXISTS - TRY AGAIN. 

This should prevent accidental overwrite of existing files and possible 
retribution by their owners. 
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The ALL aib-option ; Ihe ALL sub-option of the MPACK option simply 
subfile. 



Wiat If MPACK Aborts 

If the MPACK process aborts for any reason, the original file is left 
unchanged, regardless of v*iether you are working on the old file or a 
"new" copy of it. If you're not overwriting the old file, but 
restructuring a copy of it, the new file will not be in very good 
shape, so you probably want to delete it. If overwriting an old file 
v*ien an error or abort occurs, use KIDDEL and the "JUNK" option to 
delete all the partially used "scratch" space vAiich MPACK uses during 
restructure. 



The MPACK Dialog 



The MPACK dialog is shown below with annotations, 
been included for clarity. 



Step numbers have 



MPACK Dialog Prompts 



User Responses 



1. ENTER MIDAS FILENAME: 



MIDAS file. 



2. MPACK OR UNLOCK? 



Enter M(PACK) or U(NLOCK) . 
If MPACK, dialog skips to 
step 3. If UNLOCK, dialog 
skip to step 6. 



{MPACK Option) 



Ehter one of the 
following : 



Note 

In order to do an MPACK on a file, you need to have enough 
space for two copies of the file. MPACK always makes a copy of 
the file to work on so that in case of error, the original 
stands a lesser chance of being damaged. 

ENTER LIST OF INDEXES, ALL OR DATA: index nun±>er(s) : to be 

MPACKed , separated by 
conmas or spaces; dialog 
continues at prcanpt 6. 

A(LL) ; restructures all 
indexes in file and 
unlocks all data records; 
dialog resunes at step 6. 

D(ATA) ; restructures data 
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(EftTA Option) 
4. OK TO OVEPWRITE FILE? 



5. NEW FILENAME: 



6. ERR/LOG FILE? 



7. MILESTONE COUNT? 



file and indexes; dialog 
continues with prompt 4. 



Answer YES or NO. If YES, 
file is merely 

restructured and replaced 
(the original vanishes) . 
If NO, the next prompt 
appears: 

Ehter the name which MPACK 
should give to the 
restructured file. After 
the MPACK, you end up with 
the original file (intact) 
and a restructured version 
of this file with the 
filename you specified 
here. If you enter the 
name of an existing file, 
MPACK will return an error 
message . 

Specify optional error/log 
filename for errors and 
milestone counts: enter a 
(CR) if no err/log file is 
desired. 

Ehter appropriate nunber 
of records after viiich a 
milestone report should be 
generated, (optional) 

The file is then unlocked and restructured, and the user is returned to 
PRIMOS ccaranand level . 



Scane Examples 

The example below shows how a someviiat lopsided version of the CUSTOMER 
file could be reorganized with MPACK. the file was accessed both by 
BASIC/VM and PL/I programs, causing a disparity in the number of 
primary and secondary index entries. There are more entries in the 
secondary index subfiles than there are records in the data subfile 
because P[/I does not know how to read (or delete) secondary index 
subfile entries. By using the ALL or DATA options, the file can be 
restructured. The first example uses the "ALL" option; the second, 
the "DATA" option. 
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Btample 1; The ALL Option : 

OK, creatk 
[CREATK rev 17.6] 

MINIMUM OPTIONS? yes 

FILE NAME? custcmer 
NEW FILE? no 

FUNCTIdJ? u 

INDEX? 

ENTRIES INDEXED: 7 
ENTRIES INSERTED: 
ENTRIES DELETED: 2 
TOTAL ENTRIES IN FILE: 5 

LAST MODIFIED BY MIDAS REV. 17.6 

FUNCTION? u 

INDEX? 1 

ENTRIES INSERTED: 
ENTRIES DELETED: 
TOTAL ENTRIES IN FILE: 7 

LAST MODIFIED BY MIDAS REV. 17.6 

FUNCTIOJ? u 

INDEX? 2 

ENTRIES INDEXED: 7 

ENTRIES INSERTED: 

ENTRIES DELETED: 
TOTAL ENTRIES IN FILE: 7 

OK, mpack 
[MPACK rev 17.6] 

FILE NAME? custcmer 

'MPACK' OR 'UNLOCK' : mpack 

ENTER LIST OF INDEXES, 'ALL', OR 'DATA' : all 

ENTER LOG/ERROR FILE NAME: 

ENTER MILESTWE COtttfT: 1 
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BEGINNING PRIMARY INDEX (INDEX 0) 



COUNT 




DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL TM 


DIFF 







07-21-80 


15:47:12 


0.000 


0.000 


0.000 


0.000 




1 


07-21-80 


15:47:14 


0.002 


0.010 


0.012 


0.012 




2 


07-21-80 


15:47:15 


0.003 


0.010 


0.012 


0.001 




3 


07-21-80 


15:47:15 


0.003 


0.010 


0.013 


0.000 




4 


07-21-80 


15:47:15 


0.004 


0.010 


0.013 


0.000 




5 


07-21-80 


15:47:15 


0.004 


0.010 


0.014 


0.000 


INDEX 1 


MPACK COMPLETE, 


5. ENTRIES 


INDEXED 






beginn: 


5 
ING 


07-21-80 
SECONDARY 


15:47:17 
INDEX 1 


0.005 


0.011 


0.016 


0.002 


COUNT 




DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL IM 


DIFF 







07-21-80 


15:47:17 


0.000 


0.000 


0.000 


0.000 




1 


07-21-80 


15:47:19 


0.001 


0.001 


0.003 


0.003 




2 


07-21-80 


15:47:21 


0.002 


0.002 


0.005 


0.002 




3 


07-21-80 


15:47:21 


0.003 


0.002 


0.005 


0.000 




4 


07-21-80 


15:47:21 


0.003 


0.002 


0.006 


0.001 




5 


07-21-80 


15:47:21 


0.003 


0.002 


0.006 


0.000 




6 


07-21-80 


15:47:23 


0.004 


0.002 


0.006 


0.000 




7 


07-21-80 


15:47:23 


0.004 


0.002 


0.007 


0.001 


INDEX 


1 MPACK COMPLETE 


5. ENTRIES 


INDEXED 








7 


07-21-80 


15:47:25 


0.006 


0.003 


0.009 


0.002 


BEGINNING 


SECONDARY 


INDEX 2 










COUNT 




DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL TM 


DIFF 







07-21-80 


15:47:25 


0.000 


0.000 


0.000 


0.000 




1 


07-21-80 


15:47:27 


0.001 


0.001 


0.003 


0.003 




2 


07-21-80 


15:47:27 


0.002 


0.001 


0.003 


0.000 




3 


07-21-80 


15:47:27 


0.002 


0.001 


0.003 


0.000 




4 


07-21-80 


15:47:28 


0.003 


0.002 


0.005 


0.001 




5 


07-21-80 


15:47:28 


0.003 


0.002 


0.005 


0.000 




6 


07-21-80 


15:47:28 


0.004 


0.002 


0.005 


0.000 




7 


07-21-80 


15:47:28 


0.004 


0.002 


0.006 


0.000 


INIEX 


2 MPACK COMPLETE 


5. ENTRIES 


INDEXED 








7 


07-21-80 


15:47:29 


0.006 


0.002 


0.008 


0.002 


OK, creatk 













[CREATK rev 17.6] 

MINIMUM OPTIONS? ^s 

FILE NAME? custoner 
NEW FILE? no 

FUNCTION? u 

INDEX? 

ENTRIES INDEXED: 
ENTRIES INSERTED: 
ENTRIES DELETED: 
TOTAL ENTRIES IN FILE: 
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LAST MODIFIED BY MIDAS REV. 17.6 

F'uTKTiaJ? U 

INDEX? 1 

ENTRIES INDEXED: 5 

ENTRIES INSERTED: 

ENTRIES DELETED: 
TOTAL ENTRIES IN FILE: 5 

LAST MODIFIED BY MIDAS REV. 17.6 

FUNCTiai? u 

INDEX? 2 

ENTRIES INDEXED: 5 
ENTRIES INSERTED: 
ENTRIES DELETED: 
TOTAL ENTRIES IN FILE: 5 

LAST MODIFIED BY MIDAS REV. 17.6 

FUNCTICN? q 
OK, 

Example 2: Ihe DATA Cption ; 

OK, mpack 
[MPACK rev 17.6] 

FILE NAME^ customer 

•MPACK' OR 'UNLOCK': m 

ENTER LIST OF INDEXES, 'ALL', C» 'DATA' 

OK TO OVERBITE THE FILE? n 

ENTER NEW MIDAS FILE NAME: cust. redone 

ENTER LOG/ ERROR FILE NAME: out 

ENTER MILESTONE COUNT: _1 

BEGINNING PRIMARY INDEX (INDEX 0) 



COUNT 


DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL TM 


DIFF 





07-24-80 


10:22:07 


0.000 


0.000 


0.000 


0.000 


1 


07-24-80 


10:22:08 


0.002 


0.009 


0.011 


0.011 


2 


07-24-80 


10:22:08 


0.003 


0.009 


0.012 


0.001 


3 


07-24-80 


10:22:08 


0.003 


0.009 


0.012 


0.001 


4 


07-24-80 


10:22:08 


0.004 


0.009 


0.013 


0.001 


5 


07-24-80 


10:22:09 


0.005 


0.009 


0.013 


0.001 


INDEX MPACK COMPLETE, 


5. ENTRIES 


INDEXED 






5 


07-24-80 


10:22:09 


0.006 


0.009 


0.014 


0.001 
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BEGINNING SECCaClARY 


INDEX 1 










COUNT DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL TW 


DIFF 


07-24-80 


10:22:09 


0.000 


0.000 


0.000 


0.000 


1 07-24-80 


10:22:09 


0.001 


0.001 


0.002 


0.002 


2 07-24-80 


10:22:10 


0.002 


0.002 


0.003 


0.001 


3 07-24-80 


10:22:10 


0.002 


0.002 


0.004 


0.001 


4 07-24-80 


10:22:10 


0.003 


0.002 


0.004 


0.001 


5 07-24-80 


10:22:12 


0.003 


0.002 


0.005 


0.001 


6 07-24-80 


10:22:12 


0.004 


0.002 


0.006 


0.001 


INDEX 1 MPACK COMPLETE 


5. ENTRIES 


INDEXED 






6 07-24-80 


10:22:13 


0.005 


0.002 


0.007 


0.001 


BEGINNING SECCMARY 


INDEX 2 










COUNT DATE 


TIME 


CPU MIN 


DISK MIN 


TOTAL TM 


DIFF 


07-24-80 


10:22:13 


0.000 


0.000 


0.000 


0.000 


1 07-24-80 


10:22:16 


0.001 


0.002 


0.003 


0.003 


2 0.7-24-80 


10:22:16 


0.002 


0.002 


0.004 


0.001 


3 07-24-80 


10:22:16 


0.002 


0.002 


0.004 


0.000 


4 07-24-80 


10:22:17 


0.003 


0.002 


0.005 


0.001 


5 07-24-80 


10:22:17 


0.004 


0.002 


0.006 


0.000 


6 07-24-80 


10:22:18 


0.004 


0.002 


0.006 


0.001 


INDEX 2 MPACK COMPLETE 


5. ENTRIES 


INDEXED 






6 07-24-80 


10:22:19 


0.005 


0.003 


0.008 


0.002 


OK, creatk 












[CREATK rev 17.6] 












MINIMUM OPTIONS? yes 










FILE NAME? cust. redone 










NEW FILE? no 












FUNCTION? u 












INDEX? 












ENTRIES INDEXED: 


5 










ENTRIES INSERTED: 













ENTRIES DELETED: 













TOTAL ENTRIES IN FILE: 


5 









LAST MODIFIED BY MIDAS REV. 17.6 

FUNCTICK? u 

INDEX? 1 

ENTRIES INDEXED: 5 
ENTRIES INSERTED: 
ENTRIES DELETED: 
TOTAL ENTRIES IN FILE: 5 

LAST MODIFIED BY MIDAS REV. 17.6 
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MPACK ERRCR MESSAGES 



In addition to the messages returned throigh it by KX$RFC (those 
messages are listed in Appendix A) , MPACK returns the following error 
messages. A "fatal" error means that MPACK cannot continue processing 
as a result of the error, and will prcanptly abort. A "non-fatal" error 
is a warning only and does not impair the MPACK process. 



► UNABLE TO REACH BOTTCM INDEX LEVEL 

MPACK was unable to find a last level index block for an index: the 
file is damaged. (Fatal) 



^ INDEX SUBFILE DOES NOT EXIST 

User supplied an index number that was not defined for this file. 
(Non-fatal) 



^ FILE ALREADY EXISTS ~ TRY AGAIN 

User specified name of existing file in response to "ENTER NEW MIDAS 
FILE NAME?" prompt of "DATA" option path. MPACK will not overwrite an 
existing file in this case; the user must enter the name of a 
non-existent file. (Non-fatal) 



► INVALID KEY SEEN (IGNORED) 

This can happen Vi*ien a key is out of order in the index or the key is a 
duplicate and duplicates are not allowed in the primary index. 
(Non-fatal) 



► INVALID DIRECT ACCESS ENTRY NUMBER SEEN (IGNORED) 

Can occur vhen a record nunt)er is not greater than zero, or is not a 
vAiole number, or is greater than the pre-allocated record number limit. 
(Non-fatal) 
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DATA SUBFILE FULL 



This may occur if MPACK is being used to implement smaller index 
blocks, analler segment subfiles or smaller segment directories. 
(Fatal) 



^ INDEX FULL 

Same as above, only an index subfile is suffering in this case. 
(Fatal) 



^ ABORTING MPACK 

Message appears v*ien a "fatal" error occurred. The user should then 
delete the MPACK-created scratch files by using the "Junk" option of 
KIDDEL; or, if doing a "DATA" MPACK, delete the "new file." 
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SECTICN 13 
FOR THE AD1INISTRAT0R 



INTRODUCTION 

Ihis section is intended primarily for the MIEftS Aaministrator , or 
anyone else v*io is involved in setting up MIDAS and monitoring its 
daily use. It addresses the following fundamental concerns: 

• Concurrent process handling 

• Setting MIDAS file read/write locks 

• Using MIDAS with networks 

• Initializing MIDAS with IMIDAS 

• Library modifications 

• The new V-mode interlude 

• Releasing the internal lock using MCLUP 

• Recovering/restructuring MIDAS file entries using MPACK 

• Concurrency error detection 

• Debugging tips 

Important! 

Many of the tasks involved in MIDAS administration are directly related 
to the present method of concurrent process handling. This affects all 
new users of MIDAS, users of existing applications, and particularly 
network users, making it imperative that you familiarize yourself with 
the information in this section before bringing up the latest version 
of MIDAS on yDur system. 

CdCURRENT PROCESS HANDLING 

overview 

Concurrent process handling refers to MIDAS' s method of regulating 
simultaneous access to a MIDAS file by two or more processes. Ideally, 
such a method should not impair program performance and should prevent 
conflicting updates. 



13-1 October 1980 



SECTION 13 im4558 



Mplanentation Method 

The concurrent process handling mechanism is implonented through the 
use of several constructs: 

• MIDAS file read/write locks are set at 3; n readers and m 
writers, 

• A "lock" in shared memory that keeps track of v*io's currently 
executing a MIDAS operation 

• A semaphore wait list - a queue of processes waiting to perform 
MIDAS operations 

• The MIDAS file open and close routines, OPEM^$ and CLOSM$ (see 
Section 4) , and the "notify MIDAS" routine, mFm$, which tells 
MIDAS v^en a file is opened and closed (a substitute for OPEM^$ 
and CLOSM$; used with reiMOS SRCH$$ routine) 



Setting File Read/Wtite locks 

MIDAS no longer closes segment subfiles (index subfiles) between MIDAS 
operations. This requires that users set MIDAS file read/write locks 
to 3 (n readers and m writers) ; otherwise, concurrent processes will 
be unable to open a file segment v*iich had already been opened by 
another process. This allows more than one person to have the file 
open for writing. CREATK automatically sets the MIDAS file read/write 
lock to 3 vrfienever it creates a new file. Ibwever, you should take 
care to set the locks on existing MIDAS files to 3 v*ien bringing up the 
latest revision of MIDAS. 

Nate 

FUTIL automatically sets the read/write locks to the syston 
default v*ien it copies a MIDAS file from one place to another; 
reset the lock by typing : 

SR filename 3 

v*iere filename is the name of the copied MIDAS file. 

The Shared Lock 

lb prevent the loss of file integrity by conflicting updates v*iich 
could conceivably occur with read/write locks set at 3, MIDAS employs a 
"lock-testing" procedure to allow only one user to execute a MIDAS 
operation at a time. This is known as "single-threading". 
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Every time a call is made to MIDAS, a shared lock, located in shared 
memory segment 2020, is tested. If the lock value is zero vAien tested, 
the lock is set to the testing process's user number and the testing 
process is allowed to perform a MIDAS operation. A process can only 
obtain the lock if the lock is set at zero vAien the process checks it. 
Otherwise, some other process "owns" the lock, forcing the testing 
process to wait until the lock is freed. 

Each time a process completes a MIDAS operation, the lock is released 
and the value is reset to zero. During the lock-test operation, no 
other process is allowed to access the lock, making the "test-and-set" 
operation non-interruptible . This eliminates the problem of having a 
process alter the lock value while another process is testing it. 



The Semaphore Vfeit List 

Should the lock have a non-zero value when tested, some other process 
"owns" MIDAS and the testing process must wait its turn on a "semaphore 
wait list". Ihe wait list is just a queue of processes waiting in an 
idle state to obtain exclusive access to MIDAS so they can perform 
their respective operations. Chly one process can access MIDAS at a 
time, thus preventing damage to file integrity by simultaneous updates 
to the same file record. While more than one process may have the same 
MIDAS file open at a time, only one of these processes can actually 
operate on the i-ile at any given time because onj.y the process tiiat 
owns the lock can actually touch the file. V*ien a process releases the 
MIDAS lock, it performs a "notify" operation on the semaphore, telling 
it to activate the first process waiting on the queue (it's a FIFO 
queue) ; the next user is then released from the wait list. 



What This Means to New Users 

This concurrency handling m.ethod is entirely invisible to new users; 
however, note that OPENM$ and CLOSM$ or NTFYM$ should be used in 
opening and closing a MIDAS file in order for the concurrency handler 
to operate properly. These routines are documented in Section 6; they 
are handled automatically by CCBOL and RPG. Network users, however, 
cannot use this method of handling concurrent processes. (See below 
for details.) 



Impact on Existing Applications 

Users with existing MIDAS application programs written prior to Rev. 
16.5 have two choices: 

1. Disable the concurrent process handling method; no changes to 
existing {X"ograns are necessary. This would result in no 
performance optimization, but detection and correction of 
currency errors will still occur. Follow the steps under 
"Disabling Concurrent Process Handling", below. PRIMENET 
users: see Note, below. 
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2. SOTie or all applications programs can be modified, achieving 
increased performance. Follow the directions for program 
modification, listed below. 

Npte 

PRIMENET users should disable the concurrent process 
handling method by following the steps listed below. 
If this is not done, MIEAS will not single-thread MIDAS 
use or correct concurrency errors for files accessed 
over the net. When the current method of concurrent 
process handling is disabled, MIDAS defaults to the 
"old" method of concurrency handling. See OLD METHODS 
in Appendix D. 



Modifying Existing Programs 

If you vant to use the new method of handling concurrent processes, 
MIDAS must be notified both vhen a process is to begin using a MIDAS 
file and when the process has completed operations on the file. Fbr 
FCBTRAN and PMA users of the MIDAS call level interface, this 
requiranent means that application programs must be modified in one of 
tWD vays, described below. COBOL, BASIC/WI, PL/I and RPGII users are 
not required to make any modifications to existing or new applications 
programs written in these languages. All programs vtiich use an 
unshared library must be reloaded. See also LIBRARY MODIFICATIONS and 
The V-Mode Interlude. 



Method 1; Use NTF^$ : One method of program modification involves 
inserting calls to subroutine NTFYM$. The first call to NTFW$ should 
be inserted following the call to open the MIDAS file and just prior to 
the first MIDAS file operation. The other call to NTFYM$ should be 
inserted just before the call to close the MIDAS file. This is 
described in detail in Section 6. V4ien using NTFYM$, a MIDAS file can 
be opened and closed by general methods like the SRCH$$ routine. 



Method 2; Use OPENM$ and CLOSM$ ; The second method is to replace the 
calls vAiich open and close MIDAS files with calls to OPENM$ and CLO£M$ 
respectively. Details are provided in Section 6. 



Disabling Concurrent Process Handling 

Users may disable the new concurrent process handler, thereby returning 
to the method used in previous releases of MIDAS. Note that programs 
v*iich use the new NTFii!M$, 0PEM*1$, and CLOa^$ routines will still work 
correctly, even if this process is disabled. towever, performance 
degradation may result. 
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The following steps should be followed in disabling concurrent process 
handling : 

1. In file KPARAM, change the value of parameter SHDSEG from 
.TRUE, to .FALSE.. 

2. Fbr the unshared MIDAS library NVKDMB, run the command file 
C NVKDALB and C_INSTALminAS and reload applications programs 
vJiich use the unshared libraries. 

3. For the shared V-mode library VKEALB, rebuild the library using 
C_VKnALB and re-install MIDAS using C INSTALLMIEAS and 
C_SHAREMirAS. Application programs whicE use the shared 
library do not need to be reloaded. 

INITIALIZING MIDAS 

MIDAS installation information is included with the release of the 
master disk at each major revision. Directions for installation are 
covered there and are not dealt with in this book. A sunmary of v*iat 
the new coitmand files do and v*iere they're located is included below 
for quick reference, along with a list of the sub-UFDs contained in the 
MIDAS UFD: 

CMIM:0 Contains MIDAS utilities CREATK, KBUILD, KIDDEL, IMIDAS, 

MCLUP, REVERT, REMAKE, and MPACK. 

LIB Contains MIDAS libraries VKDAIB, NVKDALB and KIDALB. 

SOURCE Contains all source and conmand files: see below for 

details. 



SYSTEM 



Contains files K4000, K2014A and K2014B. 



Conmand Files in MIDAS 



C MIDAS 



Builds MIDAS by calling C_KII».LB, C_NVKDftLB, 
C_VKDALB, C_IMIDAS, C_MCLUP, C CREATK, C_KIDDEL, 
C_KBUILD, and C_MPACK. GopTes PARM.K and 
PARM.K.PLI (PL/I insert file) frcm MIDAS>SOURCE to 
MIDAS>SySCCM. 



C_INSTALLMIDAS Installs MIDAS by copying various MIDAS command 
files and utilities to system UFD's SYSTEM, SYSCOM, 
LIB and CMENC0. 



C SHAREMIDAS 



Shares MIDAS library, shared lock segment and runs 
SYSTEM>IMIDAS to intialize all of MIDAS. This file 
can only be run from the system console. 
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C_CREATK 

C_IMinAS 

C_KBUILD 

C_KIEALB 

C_KIDDEL 

C_IjCREATK 

C_LIST_MIDAS 

C_MGLUP 
C_MIEAS 
C_MPACK 

C_NVKnALB 

C_REJ1AKE 

C REVEOT 



C VKDALB 



Command Files in Mims>SOURCE 

Builds CREATK in MIEAS>CMr»«:0. 

Builds utility IMIDAS in UFD MIDAS>SYSTEM. 

Builds KBUILD in MinAS>CMDNC0. 

Builds the R-mode library in UFD MIDAS>LIB. 

Builds KIDDEL in MIDAS>CMIM:0. 

Builds long index version of CREATK; see Section 15. 

Makes a canpilation listing of the major MIDAS 
routines . 

Builds utility MCLUP in UFD MIDAS>C>JDtJC0. 

Builds MIDAS libraries and utilities. 

Builds MPACK in MIDASXJ1DNC0 . (See Section 12 for 
information on options.) 

Builds the unshared V-mode library NVKDALB in UFD 
MIDAS>LIB. 

Builds obsolete utility REMAKE in MIEftS>CMIM:0. See 
Appendix C. 

Builds obsolete utility REVERT in MIDAS>CMIM:o. See 
Appendix C. 

Builds the shared V-mode library, VKDALB. VKDAIB is 
put in MIDAS>LIB. K4000, K2014A, and K2014B are 
placed in UFD MIDAS>SYSTEM. 



IMIDAS; Initialization Utility 

The present method of concurrent process handling requires a special 
initialization procedure to be run during each and every cold start. 

Ihis must be run to share the segment containing the shared lock, and 
to set the lock value to zero. Make sure that no MIDAS applications 
programs are running at the time IMIDAS is invoked. You may want to 
install the coitmand file C_SHAREWIDAS in the cold start procedure to 
ensure that IMIDAS is executed and that the lock segment is shared 
during every cold start. 

lock Parameters ; Currently, MIDAS uses semaf^iore number -16 and word 
nunber '177777 of segment 2020 (the lock). These parameters, defined 
in file KPARAM, may be modified: 
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MSEWAl semaphore number 

SLSE3G segment nunber of the shared lock 

SLWCBD word number of the shared lock 

If any of these parameters are modified, the MIDAS utilities MCLUP (see 
below) and IMIDAS must also be rebuilt and installed. In addition, 
command file C_SHAREMIDAS must be modified so that the correct segment 
gets shared. Rananber that the MIDAS libraries, MCLUP and IMIDAS must 
be rebuilt also. See Section 15 for information on modifying these and 
other MIDAS parameters. 

Nate 

See also MCLUP, under MIDAS CLEANUP/RECOVERY UTILITIES, below. 



LIBRARY MODIFICATIOJS 

Ihere have been several changes to the MIDAS libraries at this rev, 
resulting in greater flexibility for both R-mode and V-mode users, and 
in overall program performance improvement. 



The Interlude 

At this rev of MIDAS, the R-^node MIDAS library, KIDALB, and the R-mode 
runtime routines have been replaced by an interlude to the V-mode 
library, VKDALB. This change results in several positive benefits, 
including: 

• reduced memory requirements — only one copy of the shared 
V-^node library, VKDALB, is needed instead of one copy of the 
R-mode routines per user. 

• reduced I/O (CPU) time — V-mode library uses the PCL 
instruction vAiich is much quicker than the SVC instruction used 
by the R-mode library to impl orient a file system call. Since a 
single MIDAS call may result in many file system calls, the 
implications are obvious. 

• only one library to warry about 

• R-mode programs using only the MIDAS library don't need to be 
reloaded. However, R-mode programs using other R-mode routines 
only need re-loading once. Ihe new shared library is 
dynamically linked during each execution, it is only necessary 
to reload KIDAIB initially when the new version of MIDAS is 
installed. 
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Nbte 



This interlude is not available to users of the PRIME P-300. 

Impact of Interlude 

The new interlude brings with it a few miscellaneous changes in the 
availability of certain internal and offline routines. The only 
internal MIDAS routines callable by R-mode and V-inode users are: 
ERROPN, FILERR, FILHER and KX$TIM. Also available are the offline 
routines PRIBLD, SBCBLD and BILD$R. 

Previously, V-inode users wsre not granted access to any internal 
routines at all, so this represents an enhancement to V-mode users, lb 
R-mode users, this represents a restriction, as they used to have 
access to all internal routines. Since the R-mode library essentially 
tracks the V-mode library in functionality, only these four routines 
just mentioned will be available. Users v*io've included calls to these 
routines in the past should note that the calling sequences have 
changed; see /^pendix D for more information. 



MIDAS CLEANUP/RECOVERY UTILITIES 

MIDAS provides tWD utilities for cleanup and recovery: one for 
reinitializing the shared lock after an abnormal program termination 
and one to recover or restructure deleted index entries in a MIDAS 
file. 



MCLUP; Releasing the Internal lock 

In the event of abnormal MIDAS program termination, MCLUP must be used 
to re-initialize the shared lock and to notify the sonaphore to avvaken 
any MIDAS process waiting on the lock. If the lock is not released, 
all MIDAS processes will be suspended indefinitely. It's quite 
possible that such a condition might go unnoticed for quite scxne time. 
Siould this condition be suspected, use MCLUP to determine v*io "owns" 
the lock. 

The MCLUP conmand takes the following form: 

MCLUP [-USER userno] 

If used without options, MCLUP re-initializes the shared lock only if 
it is held by the user v^vd issued the command. If this user is not the 
"owner" of the lock, MCLUP prints the user number of the user that does 
own it. 

When used with the "-USER userno" option, MCLUP initializes the lock 
only if held by the indicated user number; otherwise, it prints the 
nun±)er of the user that holds the lock. Simply reissue MCLUP with the 
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proper user number to release the lock so other processes can proceed. 

Automatic Notify ; Scanetimes v*ien a user quits out of a process or logs 
off the system, the lock is released but the subsequent "notify" to the 
MIEAS sanaphore does not have a chance to happen and MIEAS will cease 
to function. Ihe MCLUP utility should then be invoked in its 
optionless form. In this circunstance, MCLUP will generate an 
automatic notify to the ssnaj^iore as long as there is at least one user 
on the wait-list, and nobody else has "grahtoed" the lock. Ihis 
"autcmatic notify" feature prevents MIDAS frcm hanging up indefinitely 
because it can't signal another waiting process to ask for the LOCK. 
MCLUP prints out this message at the terminal of the user who invokde 
MCLUP vAienever an automatic notify successfully generated : 

Qeanup for unknown user successful 



HANDLING CONCURRENCY ERRORS 

Although most concurrency errors can be avoided through the lock method 
described above, there are sane that single-threading cannot prevent. 
MIDAS is able to detect and correct most concurrency errors, v*iich may 
occur v*ien more than one user accesses the same MIDAS file at the same 
time. Ihese errors are usually associated with operations that involve 

occur viien the current index entry has been deleted or i*iysically moved 
since the time the entry became current. If MIDAS discovers that the 
entry has been deleted, an error code of 13 is returned. In the event 
that the entry has been moved, MIDAS automatically locates the entry 
and continues normally. 



How MIDAS Traces the Current Record 

At the FORTRAN call level interface, the concept of current record and 
current entry is implonented as a 14-WDrd communication array. The 
ccmmunication array is an argunent in most subroutine calls to MIDAS. 
■Ihe communications array format is described below. Other information 
on this array can be found in Section 6. 
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Oc«nmunications Array Ebrmat 

The fourteen words of the array contain the following information: 

Word 1: (input) if or 1, the array contents are used 

if -1 then MIDAS array contents are not used 
(output) error status 

Wbrd 2-4: current index entry address 

word 2 bits 1-8 entry number 

word 2 bits 9-16 segment file nunber 

words 3-4 (32 bits) word offset of index block 

Wbrd 5: hash value (based on current key value) 
(for keys longer than 8 bytes (4 words) 

Wbrds 6-9: current key value (or first four words of key) 

Wbrds 10-12: current record address 

word 10 bit 1 "record locked" flag 

word 10 bits 7-16 segment file number 

words 11 - 12 word offset of record 

Wbrd 13: data control word 

bits 1-8 flag bits 

bits 9-16 primary key size (bits) 

Wbrd 14: data record length (in words) 

Note that words 2 through 9 of the conmunication array specify a 
current index entry and words 10 through 12 specify a current record. 



How MIDAS Uses the Array ; During operations involving the current 
entry (for example, "get next record") , words 2 through 4 are used to 
locate the expected position of the entry. "lb verify that the position 
contains the correct entry, MIDAS compares the data pointer in the 
entry with the data pointer in words 10 throtgh 12 of the ccarmunication 
array. If the pointers don't match, then the entry is the wrong one. 

E!ven if the pointers do match, MIDAS compares the key value in the 
index entry to the key value in the array. If they don't match, then 
the entry is the wrong one. When a wrong entry is detected, MIDAS 
searches for the correct entry. If the correct entry is not found, 
MIDAS returns an error code of 13. Note that versions of MIDAS betveen 
Ftev 16.0 and Rev 16.5 returned an error code of 13 vAien a concurrency 
error was detected. Ifeers of these earlier releases may have modified 
their applications to attonpt to recover frcsn an error 13. Since an 
error 13 presently indicates that the current index entry has been 
deleted, attempts to handle an error 13 in existing applications may 
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have to be modified. 

Limitations on Error Detection 

For indexes with keys longer than eight bytes, MIDAS may fail to detect 
a concurrency error or to correctly recover fran one. lb understand 
how this may occur, observe that a maximum of eight bytes of a key may 
be stored in the ccmmunication array. For keys longer than eight 
bytes, MIDAS stores a hash value in word 5 of the array. The hash 
value is based on the portion of the key beyond the eighth byte. MIDAS 
will fail to detect a concurrency error only if: 

• The data pointers match and the first eight bytes of the key 
match the eight bytes stored in the communication array 

or 

• The data pointers match and the hash code, based on the 
ranaining bytes, is the same as the hash code in the array 



DEBUGGING TIPS 

The MIDAS administrator will doubtless be confronted witu occssionax 
MIDAS-related problems. Before attempting to tackle than, it is 
suggested that you take time to check the following points. 



MIDAS Revision Number 

Do you have all the docimentation pertaining to the particular revision 
of MIDAS you're using? Use the VERSION option of CREATK to determine 
what software revision of MIDAS you're running and viiich version the 
file was created under. 



Incompatible Interfaces 

Does the application program in question use both a language interface 
like CCBOL and direct calls to MIDAS through FORTRAN/PMA subroutines in 
the same prograti? Ihis can lead to confusion on the part of the user 
and ultimately to a danaged file. 



Restructure History 

Vvhen vas MPACK last run against the file in question? With the USAGE 
option of CREATO, check each index and determine the percentage of the 
file that has been deleted. Performance degradation can result v*ien 
there are lots of deleted entries in secondary indexes that contain 
many duplicates. Use MPACK to unlock records; see Section 12. 



13 - 11 October 1980 



SECTION 13 im4558 



Hint: always use the "NEW" option of MPACK to prevent possible damage 
to the original file in case of error or program failure. 



Qieck the locks 

The latest version of MIDAS has two locks with v*iich users must be 
concerned; the per file read/write lock and the shared internal lock. 

Ftead/Wirite locks ; Check to make sure that per file read/write locks on 
MIDAS files have been set to 3. Prior to Rev. 16.5, MIEftS read/write 
locks were set at 2 (the standard system-wide setting) , but must be set 
at 3 to permit the new method of concurrent process handling to 
operate. Note that the lock setting is not preserved by MAGSAV or 
FUTIL TRECPY, so check the lock each time a file is processed by either 
of these operations. See Setting File Read/Vfrite locks , above. 

Internal lock ; The shared internal lock, used in gating concurrent 
processes, must be initialized with IMIDAS as described under 
INITIALIZING MIDAS, earlier in this section. The latest version of 
MIDAS specifies the shared lock to be word number '177777 of segment 
2020. The lock segment is not protected from being accidentally 
overwritten by any user, so be careful! 



New Calls and Libraries 

Are all FORTRAH/PMA programmers using the new 0PEN»4$ and CLOSM$ or 
NTFYM$ calls? If not (and intentionally) , has the concurrent process 
handler been disabled correctly as described earlier? If not, 
performance may be noticeably degraded. Have all other language 
interface programs been reloaded with the new libraries? 



Check the Sanapjiore 

The semaptwre for the concurrent process wait list has gone through a 
series of values since its debut. Currently, the semaphore value is 
-16; this value WDrks only on MIDAS versions 17 and above. Earlier 
versions of MIDAS used a setting of 64, which works for both Rev 16 and 
17 versions of MIDAS. 



Are you using Networks? 

Remember that netwark users cannot operate with the shared lock and 
semaphore-based concurrent process handler; either make sure that the 
this has been disabled according to the instructions outlined earlier 
in this section, or set the MIDAS file locks to 2. This causes the old 
method of concurrent process handling to be used. See Appendix D for a 
description. Ifetwork users may still use the new OPEbW$, CLOSM$ and 
NTFW$ calls in their programs, as these routines are not affected by 
disabling the lock-testing procedure. 
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Note 



created under previous versions, see also Appendix D. 



Multiple Libraries 

Network users may want to make a separate copy of the MIEAS library for 
their ovn use. This would be an unshared library and would contain all 
the modifications indicated previously under Pi sabl i ng Goncur rent 
Process Handling and IMIEftS; Initialization Utility , above. Making 
all the necessary changes once and saving than in a separate copy of 
the library vAiich can be used vAienever needed is a lot easier than 
making the changes every time yau vant to use MIDAS across the net. 
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INTRODUCTION 

The current version of MIDAS makes many offline routines available for 
general use. Most of these routines, including the file-building 
routines and error-logging routines have been used by MIDAS prior to 
this revision, and were previously made available to R-mode MIDAS users 
only. In conjunction with the fileH^uilding routines, a few 
newly-added routines make it possible for the user to design, create, 
and populate a MIDAS file without using the MIDAS utilities CREATK or 
KBUILD. 



What's In This Section 

lb simplify matters, this section is divided into three parts: the 
first part shows how to create and look at a MIDAS file template using 
the KX$CRE and KX$RFC routines; the second part deals with the offline 
file-building routines, PRIBLD, SECBLD, and BILD$R, and the third part 
covers miscellaneous routines like ERROFN and KX$TIM, some of v*iich may 

Oe ^cdr!i.JLlar uj UScis ui. pi.cvx(jU5 vzLOj-ijiiO ui. rij-iUnD. 



PART I. CREATING/EXAMINING A MIDAS FILE 



ALTERNATIVES TO CREATK 

Available for the first time at this revision of MiaAS are the 
user-callable internal routines KX$CRE and KX$RPC. KX$CRE is the "virork 
horse" of the CREATK utility, vAiile KX$RFC is used by nearly every 
MIDAS utility to return the configuration of a MIDAS file. These two 
routines can be used in place of CREATK as an alternate method of 
building and looking at the configuration of a MIDAS file. 

Users will find this material useful only if they want to write their 
own programs to create file templates and read file configurations 
instead of using command files that invoke CREATK and/or KBUILD. Che 
advantage of programs over coirmand files is that they can handle errors 
neatly and are not subject to subtle changes made in utility 
interfaces. 
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KX$CRE 

KX$CRE is a user-callable routine that can be used to create a MIDAS 

file from a program. It is the same routine used by O^EATK to create 

new MIDAS files and exists in all the MIDAS libraries. 



KX$CRE Calling Sequence 

The calling sequence of KX$CRE is: 

CALL KX$CRE (filnam,namlen,flags,alloc,pridef ,secdef ,errcod) 

Ihe arguments used in the above call and their data types (in 
parentheses) are: 



filnam 

namlen 

flags 

alloc 



pridef (6) 



secdef (6,17) 



errcod(2) 



The pathname of the file to be opened, tWD characters 
per word (INT*2) . 

Length of filnam in characters (INT*2) . 

Global flags ( INT*2) : see The flags Argument , below. 

Number of data records to pre-allocate if direct 
access is enabled for this file (REAL*4) . ^cify 
this nuiTt>er only if M$nACC is set in flags . This 
argument is ignored vAien creating a keyed-index file 
and may be set at 0. 



Definition array for the primary index (INT*2) . 
T^ble 14-1. 



See 



Definition array for the 17 secondary indexes 
(INT*2). secdef (1...6,i) contains the definition for 
secondary index "i," vrfiere i ranges from 1 to 17. 
See Table 14-1. 

Error code returned by MIDAS (INT*2) . If the error 
code in errcod(l) is 0, it indicates successful 
completion. If the code is less than 5000, then it 
is a file system error and KX$CRE tries to delete the 
partially created file, ignoring any errors incurred 
in the process. If errcod(l) is 5000 or greater, 
then the error code relates an error in the MIDAS 
file definition passed by the user, errcod(2) 
containing an index number, if applicable. See 
Non-File System Error Codes below. 
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On racie 14-2, the argument namlen does not have to be declared as 
Sr^lf as implied in the book. Itiis is the default however. 
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The Flags Argument ; The flags argument indicates the file type and 
the READ/WRITE lock setting of the file to be created in this call. 

The flags argument value is set with the following keys: 
Key Function 



M$nACC 



M$NRNW 



M$NR1W 



Enables file 
contains the 
pre-allocate. 



for direct access. alloc 
initial nionber of records to 



Sets file lock to n readers 
This is the default even 
specified. 



and n writers, 
if M$NRNW is not 



Sets file lock to n readers and 1 writer. 
Ihis must be used if the file is intended for 
access by more than one user at a time and at 
least one of those users is to access the file 
over PRIMENET. 



Note 



Ihe file : 
exclusive. 



keys, MSNRNW and M$NR1W, are mutually 



The Pridef and Secdef Arrays : The pridef and secdef arrays must be 
assigned values (by the user) to indicate the characteristics of the 
primary index and any secondary indexes to be included in the file 
template. These arrays are passed by the user's program to KX$CRE, 
v*iich then uses this information to build the file template. 

The six-element one-dimensional array pridef (1... 6) ? contains the 
information needed to define the primary index. Similarly, secondary 
indexes are defined by the twa-dimensional secdef array, where 



secdef (1... 6, i) defines secondary index 
arrays are INTEGER*2. 



All the elements in these 



the six elafnents of each array are listed in 'feble 14-1. The flags 
listed in Table 14-2 are divided into three groups. Ihe first group 
defines special index subfile characteristics; the second defines key 
type and the third tells whether the key size is supplied in bits, 
bytes or words. These flags are passed to KX$CRE in much the same way 
as the MIDAS flags are passed to the various MIDAS subroutines as 
discussed in Section 6. 
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Table 14-1. Pridef and Secdef Array Elements 



Array Elanent 
pridef (1) 

secdef (l,i) 



pridef (2) 
secdef (2, i) 

pridef (3) 

secdef (3, i) 

pridef (4) 

secdef (4, i) 
pridef (5) 

secdef (5ri) 
pridef (6) 
secdef (6, i) 



Description 

Cbntains one or more flag values specifying the key 
type and key size, plus viiether or not the primary 
index is to be double length. See Table 14-2. 

Defines the key type and size of the "ith" secondary 
key: also determines the duplicate status of the 
key and defines the length of the index subfile 
(i.e., tells if it's double-length). See Table 14-2 
for key-type flags. 

Primary key size in bits, bytes or words, depending 
on key size flag specified in pridef (1). 

Secondary key size in bits, bytes or words, as 
indicated by key size flag supplied in secdef (l,i) . 
If this elanent is 0, the index does not exist. 

Data record size. If 0, means variable-length 
records. 

Secondary data size: see Appendix C. Supply a if 
this feature is not desired. 

Level 1 block size. Supply a to use default block 
size (1024 words) . 

Level 1 block size: same as above. 

Level 2 block size. Supply a to use default block 
size. 

Level 2 block size: same as above. 

Last level block size: = use default. 

Same as above. 
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Table 14-2. Flags for pridef(l) and secdef (1) 



Flag 

M$DLNG 
M$DUPP 



Index-Specific Flags 

Meaning 

DDuble length index 

mplicates permitted for this key 
(illegal for the primary key) 



Flag 
M$BSTR 
M$SPFP 
M$DPFP 
M$SINT 
M$LINT 
M$ASTR 



Key Type Flags 

Meaning 
Bit String 

Single-precision floating point (REAL*4) 
Double-precision floating point (REAL*8) 
Short (one-ward) integer (INT*2) 
Long (tvro-word) integer (INT*4) 
ASCII string 



Flag 
M$BIT 
M$BYTE 
M$WC»D 



Key Size Flags 

Meaning 

Key length is specified in bits 

Key length is specified in bytes 

Key length is specified in words 
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Using the Flags ; *Ib use the flags, select the appropriate flags, one 
from each of the three groups, except for the first group from vAiich 
you may choose none, one or both flags. Assign them to the first ward 
of the pridef or secdef array in the follovdng manner: 

SBCDEF{1,1) = M$DUPP + M$ASTR + M$WaE® 

Ihis defines an ASCII key that allovs duplicates, and v*iose length, 
defined in words, is supplied in SE!CDEF(2,1) . 



Non-File System Error Codes 

Errors encountered during the building of a template may originate in 
the file systan or in MIDAS, and may result from bad user argiments or 
from some internal MIDAS problem. The error codes v*iich the user is 
most likely to see are listed in Table 14-3. 



KX$RFC 

KX$RFC is a user-callable routine that returns the file configuration 
of an already existing MIDAS file. Its calling sequence is essentially 
the same as that of KX$CRE, except that most of the arguments are 
returned by KX$RFC instead of being set by the user. Its calling 
sequence and arguments are described below. 
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'feble 14-3, KX$CRE Error Codes 



Code Meaning 

ME$BAS Allocation size is bad. Ihe nunber specified in 
alloc was: (a) less than 1.0, (b) not a vrfwle 
number, or (c) too big to allocate alloc records 
(the user-supplied number passed in the alloc 
argument) given the default segment directory 
and segment subfile lengths. 

ME$BDS Data size is bad for one of these reasons: 

• Data size is negative. 

• Data size in pridef (3) is meaning 
variable-length data records, but the file 
is configured for direct access v*iich 
requires fixed-length data records. 

ME$BKS Key size is bad. Ebr example: 

9 ¥ay size is too big. Ihe limit is 16 words 
except for ASCII strings v*iich may be up to 
32 words. 

• Key size is negative. 

• Primary key size is 0. 

ME$BKT Key type is bad. 

ME$BL1 Level 1 block size is bad. The block size must 

be positive, not larger than RECLNT (1024 
WDrds) , and must hold at least two index 
entries. 
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'fable 14-3. Error Codes (continued) 



ME$BL2 Level 2 block size is bad. 

ME$BLL Last level block size is bad. When building a 
secondary index, this error may also be caused 
v*ien the secondary data size, secdef(3,i), is 
too large, in comparison to the block size, to 
fit the mandatory two entries per block. 

ME$CBD Index can't be double length. The user may have 
specified the primary index as double length and 
then defined secondary index one, or specified 
secondary index i as double length and then 
defined secondary index i+1, or the user may 
have specified secondary index 17 as double 
length. 

ME$NnA No duplicates allowed. Ihe user specified the 
flag M$DUPP in pridef (1) that is not permissible 
because duplicates are not allowed for the 
primary key. 

Note 

All of the flags and codes listed above are defined in 
SYSC0M>PA»1.K. 
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KX$RFC Calling Seauence 

Ihe KX$RFC calling sequence is: 

CALL KX$RFC (filnam,namlen,flags,alloc,pridef ,secdef ,errcod) 
The arguments, their meanings and their data types are: 



filnam 



namlen 



flags 



alloc 



pridef (6) 



Ihe pathname of the MIDAS file v*iose configuration is 
to be returned (INT*2) . (supplied by user) 

Length of filnam in characters (INT*2). (supplied by 
user) 

Global flags: M$DACC is the only possible flag 
returned (INT*2) . (returned by KX$RPC) 

Number of data records pre-allocated if direct access 
enabled, otherwise 0.0 is returned (REAL*4) . 
(returned by KX$RFC) 

Definition array for the primary index (INT*2) . 

Viei,arnea Dy iSA^nr*-) 



secdef (6,17) Definition array for the 17 secondary indexes 
(INT*2) . secdef (1... 6, i) contains the definition for 
secondary index i. (returned by KX$RPC) 



errcod 



Error code or if no error 
KX$RFC) 



(INT*2). (returned by 



The arguments are very similar to those used in calls to KX$CRE, and, 
with the exception of a few minor notes vAiich appear below, the user is 
referred to the previous discussion on KX$CRE for details on the 
arguments used in this call. 

Notes on KX$RFC Arguments 

Ihe flags argument is not supplied by the user in a call to KX$RFC, but 
is instead returned by a successful call to that subroutine. If the 
file is a direct access file, the flag M$DACC is returned; otherwise, 
flags is returned as 0. If the file is not enabled for direct access, 
the alloc argument will be zeroed by KX$RFC. 
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Pridef and Secdef Flags ; The flags returned on this call are: 

• M$BSTR,M$MSPFP, M$DPDP, M$SINT, M$LINT and M$ASTR represent 
possible settings for bits 1-4. 

• M$DLNG and M$DUPP represent the setting of bits 5 and 6 
respectively. 

• M$BIT, M$BYrE, M$WCeD represent possible values of bits 6-7. 
(M$WOFUD is generally not returned by KX$RFC.) 

Element secdef (2, i) is returned as if there is no index "i" in this 
file. 

Errcod ; This is a one-word argument in this call instead of a two-word 
array. Error codes less than 5000 indicate file system errors. The 
only returned code greater than 5000 is: 

ME$NMF 

v*iich means this file is not a MIDAS file. This could be true for 
several reasons, including: 

• Ihe file is not a SAM segment directory 

• Segment subfile (file descriptor subfile) does not exist 

or 

• Segment subfile does not contain the appropriate flags to 
indicate that the file is a MIDAS file 

There are other messages returned by KX$RFC. They are listed in 
Appendix A along with the other MIDAS error messages that are common to 
several MIDAS routines. KX$RFC is called by nearly all of the MIDAS 
utilities, and therefore, any message it returns is more than likely to 
be associated in the user's mind with the routine that was just called 
v*ien the error occurred. Thus, these messages are treated in the place 
v*iere the user is most likely to look for explanations of error 
messages. 
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On page 14-11, the statement under Why Use Offline Routines? 
states that off-line roatines are faster because they are not 
shared. Biis is only part of the actual story. Offline routines 
are not meant to be ^ared and therefore are not concerned with 
multi-user access to a file. Oherefore they don't write out index 
blocks after each index entry is added to a file, as ADD1$ does. 
(Online routines must always write index blocks out to tiie file 
after each operation on the block so that the file will not be 
damaged by concurrent access and so each user will have a 
consistent view of the file while accessing it.) By not writing 
out the index blocks each time, a considerable amount of I/O 
overhead is saved, making off-line routines faster tiian their 
online counterparts. In addition, the off-line routines bypass the 
concurrent process handling method which normally single-threacfe 
MIDAS use for online routines. Thus only one person can have 
access to a MIDAS file at a time when that file is being processed 
by an off-line routine. ^ 
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PART II. FILE-BUILDING ROUTINES 



ALTERNATE FILE-BUILDING METHODS 

The second part of this section describes several ways of building 
MIDAS files v*iich were not covered in Section 3. Specifically, there 
are three offline file-building routines available in the current MIDAS 
library: PRIBLD, SECBLD and BILD$R. These routines can be called from 
any user program to add index and data subfile entries to keyed-index 
or direct access MIDAS files. Data entries can have fixed or 
variable-length records and can be sorted or unsorted. R-mode users 
may already be familiar with these routines — they were previously 
kept only in the R-mode library. People v*io've used these routines in 
the past should consult Appendix D for an explanation of changes made 
to them with the current version of MIDAS. 

Briefly, the functions of these routines are: 

• BILD$R builds MIDAS data and index subfiles from sorted/unsorted 
input data. 

• PRIBID builds an empty primary index subfile and data subfile 
from sorted input data. 

• SECBLD builds an empty secondary index subfile from sorted input 
data. 

You can use these routines by calling them from programs written in 
FTN, BASIC/VM, PL/I, or any other Prime language. Consult the 
appropriate reference guides and user manuals for details on calling 
external routines. rfewever, it is assumed that the offline routines 
described in this section are most useful to FORTRAN or PMA 
prograimers. 



Why Use Offline Routines? 

Because offline routines are not shared, only one user can "have" than 
at a time; thus they are faster than the online routines like AE01$. 
If you have networks, you might use PRIBLD, SECBLD and BILD$R as part 
of your "network library" package; see Section 13 for details. 

These routines also provide the user with tools for building files with 
concatenated keys or adding secondary data entries, neither of v*iich 
are supported by KBUILD. 
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Restrictions 

Offline routines cannot be called by more than one user to operate on 
the same file. Once the file is opened by one of these routines, no 
one else can invoke any MIDAS routine to work on that file. However, 
it is possible for more than one of these routines to be called from 
the same program to work on the same file, as long as they don't access 
the same index subfile concurrently. This allows the user to build an 
entire file from a single program by calling the file-building routines 
in the proper sequence. 

It is also not possible to build more than one MIDAS file at a time 
from the same program using offline routines. In addition, it is not a 
good idea to access a file being built by one or more offline routines 
or a utility with any of the online routines. Doing so can damage the 
file. 

The offline routines do check to see that they are not accessing the 
same index subfile of a given MIDAS file simultaneously v*iile building 
it. However, they cannot guarantee that the file is not being accessed 
by an online routine or utility v*iile it's being built. 



Which Routine to Use 

Review these guidelines before deciding v*iich routines to use for MIDAS 
file-buildir^. Make sure you understand v*iich routines should be used 
together v*ien building a file. 

Note 

When using any of the routines discussed in this section, 
rononber to $INSERT all of the following insert files into your 
FORTRAN programs: 

SYSCCM>PARM.K 
SYSCOM>ERRD.F 
SYSCOM>KEYS.F 

Use PRIBLD ; Use roiBLD when all of the following are true: 

• You want to build a primary index and data subfile 

• Your data is sorted on primary key 

• The MIDAS file being built contains NO entries v^iatsoever: see 
Note below. 
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Use SECBLD ; Use SECBLD v*ien all of the following are true: 

• You are building one or more secondary index subfiles 

• Your input data is sorted on a secondary key field 

• The secondary index subfile (s) to be built contain NO entries 
(See Note below.) 

The input data must contain a copy of the primary key associated with 
each particular secondary key entry you want added to the file. SECBLD 
locates the primary key entry in the index subfile so the secondary 
index entry can be added, 

PRIBLD and SECBLD are much faster than BILD$R, so try to use them 
v^ienever possible unless one or more of the above conditions are not 
true. 

Note 

If you're attempting to reHDuild an existing file that 
previously contained entries, make sure that each index you 
want to build from sorted data is truly empty, and does not 
contain obsolete pointers to data subfile entries that no 
longer exist. Use MPACK or KIDDEL to clean out the index 
subfiles before attempting to re-build than with sorted input 
data. 

Use BILD$R ; Use BILD$R vA\en these conditions occur in the combinations 
indicated: 

• Your input data is not sorted by the index to be built 

and/or 

• Your output (MIDAS) file already contains entries in the subfile 
to be built 

Calls to PRIBLD, SECBLD and BILD$R can be made from the same program to 
build a single MIDAS file as long as you don't attanpt to build the 
same index subfile from both BILD$R and PRIBLD or SECBLD at the same 
time. 
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Cautions 



There are several important points you should keep in mind v*ien using 
the offline file-building routines: 

• Programs that make calls to BILD$R should beware of making calls 
concurrently to HilBLD and/or SECBLD (and vice versa) because 
conflicts may occur v*ien two routines try to access or modify 
the same index subfile. When this happens, the second routine 
to access that subfile will report an error and will abort 
unless an alternate return is provided by the program. (See the 
list of error messages that follows each routine.) 

• Programs that use any of these routines to build a MIDAS file 
should not be run at the same time as application programs vAiich 
access the same MIEftS file. 

• A MIDAS file opened for use by any of the file-building routines 
cannot be in use by any other user or process, for reading or 
writing. 

• PRIBLD, SECBLD, and BILD$R can only be used to build a single 
MIDAS (output) file. There is no cap^ility for processing more 
than one output file through any of these file-building 
routines. 

The remainder of this section describes the callir^ sequences and the 
functions of PRIBLD, BILD$R and SECBLD. 



Event Sequence flag 

PRIBLD, SECBLD and BILD$R each use the same "flag" argument in their 
calling sequence. This flag, called segflag in the argunent list, is 
used as a coirmunications tool between the routine and the user. With 
it, you tell the routine when to start and stop processing. In return, 
the routine tells you the state of the build operation. It can have 
one of four values as shown in T^ble 14-4. When first calling one of 
these routines from a program to add an entry, supply a flag value of 
in the calling sequence; this is essentially an initialization request 
to the routine. It tells the routine to start processing the data 
provided by your program. When the first record has been successfully 
processed, the routine sets the flag value to 1; the flag remains set 
at 1 until the last entry is processed. At this point, the user's 
program should issue a " final izat ion" request, setting the event 
sequence flag to 2. This is done by making another call to the routine 
in v*iich seqflg has a value of 2; every other argument in the calling 
sequence, except for the unit and altrtn arguments, is ignored, and may 
have a value of 0. A finalization request must be used to close the 
currently opened index subfile before another index subfile can be 
opened. When the finalization request is fulfilled, the routine will 
set the seqflg value to 3, indicating that the particular subfile has 
been closed. 
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>v'snt Sequence Flag Values 
Value Pfeaning 

Set by user and passed to routine to 
signal that first record of input data is 
to be processed; this is essentially an 
initialization request. 

1 Set by routine after first record has 
been processed. Remains set at 1 until 
user sets it to 2. 

2 Final izat ion request: set by the user 
and passed to routine after last entry in 
input data has been processed. 

3 Set by the routine to indicate that 
finalization is complete; if more than 
one index subfile is open, a separate 
finalization request must be made for 
each one. The routine acknowledges the 
closing of each index by setting the flag 
to 3. 



Since these routines are all serially reusable, the build process can 
be restarted for a new index subfile by setting seqflg to again 
(especially useful in BILD$R and SECBLD) . 

General Use of Sequence Flag ; This is a very generalized example of 
how the process control flag is used: 

C INITIALIZATION REQUEST 
SEQFLG = 



SET UP ARGUMENTS FC5? CALL 



CALL routine-name (SEQFD3, argiments ) 

C FINISH UP 

C MAKE CLOSE REQUEST 

SEQFLG =2 /*REQUEST TO CLOSE 
CALL routine-name (SEQFLG, arguments ) 
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Error Ifandling 

Althotgh the alternate return feature is an acceptable method of 
handling errors, it is not consistent with the ever growing trend 
towards modular programming. The use of non-local "GOTO's" is frowied 
upon by all proponents of modular structure, and the use of flags to 
pass error status codes betveen the main program and the routines it 
calls is highly favored. Errors are then handled through a normal 
return to the calling program at vftich point the flag is checked and 
some sort of action is taken, usually by an on-unit (PL/I) or other 
exception handler. 

Recording Errors ; Errors that occur during the file-building process 
can be written to a disk file instead of appearing at the terminal. 
Use ERROFN to open and name such a file. Similarly, milestones can be 
recorded in this file by calling KX$TIM. 



PRIBLD 

The PRIBLD routine builds a primary index subfile and adds the 
corresponding data records to the data subfile. The input file must be 
sorted by primary key field and the MIDAS (output) file must be empty. 
This is because E^IBLD cannot add sorted primary key entries to an 
index subfile that already contains key values. PRIBLD is the fastest 
method of building a primary index subfile; if you're concerned about 
speed and performance, use PRIBLD instead of BILD$R whenever possible. 
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PRIBLD Calling Sequence 

PRIBLD's calling sequence is: 

CALL PRIBLD (seqflg, primkey, data, dlength, unit, altrtn, danum) 

Ihe arguments are all integer (INT*2) except for danum , vhich is a 
floating-point (REAL*4) number used in building direct access MIDAS 
files only. 



seqflg 
primkey 

data 
dlength 



unit 



altrtn 



dar 



"Ihe event sequence flag, see I^ble 14-4, above. 

A nimeric variable or a one-dimensional array, v*iich can 
be an integer or real number, depending on the key type, 
vAiich contains the primary key value to use on this 
call. 

A one-dimensional array containing the data to be added. 
If dlervgth is zero, data may also be zero. 

The length of data in vrords. For fixed-length records, 
if dlength is less than the record size originally 
defined for the file, the entry written to the MIDAS 
file will be padded with 0's. Excess data is ignored. 
Bbr variable-length records, specify the exact length of 
the record being added. 

The file unit on vAiich the MIDAS file is opened. 

The number of a statement in the program to be used as 
an alternate return; if is supplied for the altrtn 
argument, control returns to PRIMOS in the event of an 
error. See Error Handlers , below. 

Ihe entry number for direct access files; this is a 
REAL*4 number. If the indicated entry slot is already 
occupied, the entry is added to the end of the data 
subfile. Specify a for this argument if the MIDAS 
file being built is a keyed-index file. ' 
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PRIBLD Error Messages 

Vt\en using PRIBLD, one has to be careful of other users accessing the 
file that is being built. If this happens, reiBLD may not be able to 
recover from the error and the file will probably be garbled. If one 
of the following error messages is encountered, the user can call 
PRIBLD to finish building the index, (set SEQFDG to 2) and the file 
will be reasonably complete, except for the problan as indicated by the 
error message. If a file system error occurs (i.e., one that doesn't 
appear in the list below) , you can be sure that the file will be 
damaged. In this case, zero the file with KIDDEL, att^npt to figure 
out what happened, and try again. In both kinds of errors, HIIBLD 
usually prints out the key supplied by the user (i.e., the entry it vas 
trying to process) , along with the error message. 



^ CAN'T IBE PRIBLD AND BILD$R SIMULTANEOUSLY 

Ihis is a fairly obvious message warning the user against simultaneous 
access to the primary index subfile. This can happen v*ien the user has 
added one or more entries to the primary index with BILD$R and has now 
called PRIBLD vAiich generates this message. Either continue adding 
entries or finish building index with the appropriate calls to 
BILD$R, but not PRIBLD. 



► ILLEC3AL SEQFLG 

The value of SEQFDo is incorrect. Remember, the first call to PRIBLD 
to add an entry must have a SEQFLG of vAiich PRIBLD will return as a 
1. Subsequent calls to PRIBLD to add additional entries must continue 
to have a SEQFLG of 1. Ihe final call to PRIBLD to close building 
index for that MIDAS file must have a SEQFLG of 2 and PRIBLD will 
return it as a 3. 



► NOT A VALID MIDAS FILE 

Ihe first time PRIBLD is called to add an entry (SEQFLG = 0) to the 
primary index of an MIDAS file, PRIBLD calls KX$RFC both to verify that 
the file is indeed a valid MIDAS file and to gather certain 
configuration data needed to build the file. See Appendix A for a list 
of other messages that may be returned by KX$RFC through PRIBLD. 



► INDEX NOT ZEROED 

The file must not contain any entries if PRIBLD is to be used to build 
the primary index. Use KIDDEL to zero the file. 
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^ INMX 0: INDEX BLOCK SIZE GREATER THAN MAXIMUM DEFAULT 

This is a fatal error that may occur on the first call to KlIBLD to add 
an entry. The argument RECLNT in the MIDAS paramter file KPARAM is 
less than the block size specified for some index level. Either fix 
the file or fix RECIWT in KPARAM and rebuild MIDAS before continuing. 
(See Section 15 for additional details.) 



^ KEY SEQUENCE ERRCR 

The key provided in the current call is less than or equal to the key 
provided in the previous call to PRIBLD. 



► INDEX 0: +0.nnnnnnn E4fin INVALID DIRECT ACCESS ENTRY NUMBER 

This error occurs during direct access file processing only. It can 
happen for one of three reasons: 



1. The record nunber supplied was less than zero 

2. Ihe record number supplied was not a whole nunber 

3. The supplied number exceeds the number of entries 
pre-allocated by CREATK 

It is possible the user may have changed this number with CREATK and 
forgot to MPACK the file to effect the change. Try MPACKing the file. 



► DATA SUBFILE FULL 

No more entries may be added to the data subfile and therefore to the 
primary index. However, a call to PRIBLD to finish building the 
primary index (with SEQFD3 = 2) may still be made. 
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SECBED 

The SECBLD routine builds secondary index subfiles from input data 
sorted by secondary key. Ihe index subfile being built must not 
contain any entries prior to the calling of SECBLD. A copy of the 
primary key must be included as one of the argunents in the call so 
that SECBLD can make the appropriate connections between the data 
subfile entries already in the file and the secondary index entries 
being added. 

When making calls to SECBLD in a program, avoid making calls to BILD$R 
that attanpt to open the same secondary index subfile. If BILD$R 
already has the secondary index subfile open v*ien SECBLD is called, 
SECBLD will return the error message: 

^ CAN'T USE SECBLD AND BILD$R SIMULTANEOUSLY 



SECBLD Calling Sequence 

The calling sequence of SECBLD is: 

CALL SECBLD (seqflg,seckey,pkey, index, secdat,sdsiz,unit,altrtn) 

There are no special arguments for direct access files; this is 
because the data entries have already been added and the record numbers 
need not be supplied in order to add secondary index entries. The 
complete argument list is given below. Data types are given in 
parentheses. 
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seqflg 
sec key 
pkey 
index 
secdat 



sdsiz 



unit 



altrtn 



Ihe event sequence flag, described 
(INT*2) . 

The secondary key value to be added 
subfile (INT*2) . 



in l^ble 14-4 



to the index 



The primary key value that 
record as seckey {INT*2) . 



references the same 



The secondary index subfile number being built 
during this call to SECBLD (INT*2). 

Ihe secondary data to be stored in this index entry 
(INT*2) . This applies only to indexes for vAiich 
the secondary data feature was chosen during index 
definition. Specify if you don't want to add any 
secondary data for this particular index. 

The size of the secondary data supplied in this 
call; specify in words (INT*2). Specify a if 
you supplied for the previous argument. 



The file unit on 
(INT*2) . 



v*iich the MIDAS file is open 



The number of the statement in the calling program 
to v*iich control returns in the event of an error 
( INT*2) . If (no alternate return in program) . 
SECBLD exits to PRIMOS vAien an error occurs. 



SECBLD Error Messages 

Like PRIBLD, SECBLD is fast and efficient but is not able to protect 
the file it is working on from damage caused by outside interference 
during the file-building process. Many of the error messages returned 
by SECBLD are quite similar to those returned by reiBLD. The same 
error-handling method described under PRIBLD applies to SECBLD, so it 
wi±l not be repeated here. The symbols "##" as used in the message 
representations below are replaced by a secondary index number vrfien 
actually returned by SECBLD. 



^ INDEX ##: DOES NOT EXIST 

The indicated index is either an invalid index number or simply doesn't 
exist in the MIDAS file. Either go back ars3 ADD the index wi1± CREATK 
and try again or remove all references to this index frcMti the program. 
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^ INDEX ##: CAN'T USE SECBLD AND BILE^R SIMULTANEOUSLY 

This means that the user may have added one or more entries to this 
index with BILD$R and has now called SECBLD to add an entry to it. The 
user may continue adding entries or finish building this index with the 
appropriate calls to BILD$R, but not to SECBLD. 



^ INDEX ##: ILLEGAL SEQFL3 

The value of SEQFLG is incorrect. See the discussion for this error 
under PRIBLD Error Messages, above. 



^ INDEX ##: NOT A VALID MIDftS FILE 

This message is returned for the same reasons given for PRIBLD, above. 

► INIffiX ##: NOT ZEROED 

The index must not contain any entries if you're trying to use SECBID 
to build it. Use KIDOEL to zero this index or to zero the entire file. 

^ INDEX ##: INDEX BLOCK SIZE GREATER THAN MAXIMUM DEFAULT 

See the discussion under PRIBLD Error Messages , for an explanation of 
this error message. 

^ INDEX ##: KEY SEQUENCE ERROR 

The supplied secondary key is either less than the secondary key 
supplied in the last call to SECBLD for this index, or is a duplicate 
of the secondary key supplied in the last call to SECBLD for this 
index, and the index does not allow duplicates. 
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^ INEEX ##: CAN'T FIND PRIMARY KEY IN FILE 

SECBLD was unable to find the key value supplied for the pkey argument. 
The index subfile does not contain this value. When this error occurs, 
both the primary key (index 0) and the secondary key supplied in the 
call to SECBLD are displayed with the above error message. 



► INDEX ##: INDEX FULL 

No more entries may be added to this particular secondary index, but a 
call to SECBLD to finish building this index (set SEQFLG to 2) may 
still be made. 
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BILD$R 

BILD$R can be used to build the primary index subfile and data subfile, 
as well as any or all of the secondary index subfiles associated with a 
particular MIDAS file. BILD$R processes both sorted and unsorted data, 
and can add entries to files that already contain index entries in 
primary and/or secondary subfiles; it can also work on MIDAS files 
that are essentially anpty. 

Calls to BILD$R should not be made concurrently with calls to PRIBLD or 
SECBLD or the calling program will abort (in the absence of an 
alternate return) . 



BIID$R Calling Sequence 

The calling sequence of BILD$R is: 

CALL BILD$R (seqflg,key,Ftouf ,bufsiz,danum,index,unit,altrtn) 

The arguments for BILD$R are described below. Data types are shown in 
parentheses . 



seqflg 

key 

lt>uf 



bufsiz 



danum 



index 



unit 



The event sequence 
(INT*2) . 



flag; see "I^ble 14-4 above 



The primary or secondary key value to be 
this call (INT*2) . 



added on 



If a primary index entry is being added, this is 
the data subfile entry only (INT*2). If adding a 
secondary index entry, this is the primary key that 
references the same data record as the secondary 
key entry being added. (If you're using secondary 
data, it should be placed in pbuf , immediately 
following the primary key value.) 

The size of pouf in words (INT*2) . See tfote below. 

The record entry number for direct access files; 
this is a REAL*4 number. If the indicated entry 
slot is already occupied, the entry is added to the 
end of the data subfile. Specify a for this 
argument if the MIDAS file being built is a 
keyed-index file, or if adding a secondary index 
entry. 

The number of the index subfile being built on this 
call to BILD$R (INT*2) . (Supply if building the 
primary index.) 



The file unit number on vhich 
opened (INT*2). 



the MIDAS file is 
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altrtn The alternate return in the calling program to 
v*iich control is passed in the event of an error 
(INT*2), If specified as 0, the program will abort 
and return you to PRIMOS command level. 

Note 

When adding a primary index entry, the bufsiz argunent is 
ignored unless the file contains variable length records. In 
this case, bufsiz represents the length of the data record 
only. When adding a secondary index entry, supply a if 
you've already put the desired secondary data into F^uf . If 
non-zero, bufsiz indicates the total size of the primary key 
and the size of the secondary data supplied in pbuf . Extra 
secondary data is ignored and insufficient data is padded with 
0's. Note that this differs from the way FRIBLD and SECBLD 
treat a data size specification of 0. 

BILD$R Error Messages 

Like PRIBLD and SECBID, BILD$R cannot recover from simultaneous access 
errors, so the user should beware of them. Both file system errors and 
BILD$R-specific errors may be returned v*iile using BILD$R to build a 
file. The BILD$R-specific ones are listed below. Where the error 
messages are the same as those given previously for E^IBLD and SECBID, 
the reader is referred to those error message discussions. 

Ebr both types of errors, BILD$R will close all the internal files it 
has opened and usually will print the key supplied by the user along 
with the appropriate error message. 



► INDEX ##: DOES NOT EXIST 

The indicated index is either an invalid index number or doesn't exist 
in the MIDAS file. The user may go back and ADD the index with CREATK 
and try again or remove all references to this index from the program. 



^ INDEX ##: CAN'T USE BILD$R AND PRIBLD/SECBLD SIMULTANEOUSLY 

This can happen v*ien the user has added one or more entries to this 
index with E«IBLD or SECBLD and then calls BILD$R to add an entry to 
the same index. You can either continue adding entries or finish 
building this index by making the appropriate calls to either PRIBLD or 
SECBLD, but not to BILD$R. 
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^ INDEX ##! ILLEGAL SEQFL3 

The value of SEQFLGI is incorrect; refer to the discussion of this 
under PRIBLD Error Messages above. 



^ INDEX ##: NOT A VALID MIIAS FILE 

See the discussion for this under PRIBLD Error Messages . 

► INDEX ##: rniMX BLOCK SIZE GREATER THAN MAXIMUM DEFAULT 
See the discussion for this under PRIBLD Error Messages. 



^ INDEX 0: DIRECT ACCESS FILE - INDEX OF -1 AND ENTRY # REQUIRED FOR 
PRIMARY KEY 

The user is att«npting to build the primary index of a direct access 
file. In such cases, an index number of -1, not 0, must be used and a 
REAL*4 entry number must be supplied in array (3-4) . 



► INDEX 0: +0.nnnnnnn E+nn INVALID DIRECT ACCESS ENTRY NL»1BER 
See explanation under PRIBLD Error Messages above. 

► INDEX ##: KEY SEQUENCE ERRCS^ 

The supplied key is a duplicate of a key already entered in the 
indicated index and the index does not allow duplicate entries. BILD$R 
does check for the case v*iere there is an entry already present in an 
index that does not allow duplicates to see if this entry points to a 
deleted record. In such cases, the new entry will be made on top of 
the old entry. 

^ INDEX ##: CAN'T FIND PRIMARY KEY IN FILE 
See SECBLD Error Messages above. 
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^ INDEX ##: INDEX FULL 

No raore entries may be added to this particular index ^ but a call to 
BIID$R to close building this index (seqflg = 2) may still be made. 



^ INDEX 0: DATA SUBFILE FULL 

No more entries may be added to the primary index, but a call to BILD$R 
to finish building the primary index (seqflg - 2) may still be made. 



Offline Routine Example 

Suppose an airline has a file containing flight number, origin, 
destination, departure time, arrival time, etc. information. Each 
record has several fields containing this information, but there are no 
keys by vAiich the file can be searched. Furthermore, the airline 
desires to search on a key that is a combination of several fields, for 
example, flight number, origin and destination. The airline decides to 
put this information into a MIDAS file. The flight number, origin and 
destination fields will be concatenated to form the primary key, and 
the date, departure time, and arrival time fields will become secondary 
keys in the MIDAS file. Because KBUILD cannot handle concatenated 

Keys, tile 0J.txJ.ne j.iie~Duj.J.uiny rOui.j.iicS arc uiic i.u<saj. L.UUJ.5 J.UJ. 

building the MIDAS file. Ihe original sequential disk file is used for 
input, and it is listed below, along with a COMOUT file of the CREATK 
session in v*iich the MIDAS template used in this application was set 
up. The example program uses all three file-building routines, as some 
fields in the input file are sorted and others aren't. 

the Input File : The sequential input file, called INPUT_FILE, is made 
up of eight fields: 

195 BOS LOG NWK EWR 11/05/80 12:00 13:00 

205 BOS LOG NYC JFK 11/05/80 12:15 12:50 

305 BOS LOG NYC LGA 11/05/80 12:30 13:10 

696 CHI ORD WOR WC» 11/05/80 10:45 12:15 

106 NWK EWR ORL ORL 11/06/80 08:40 11:55 

749 NYC DGA CHI ORD 11/05/80 16:00 18:30 

650 W(» ViOR BOS LOG 11/05/80 12:45 13:15 

Ihe only fields that are in sorted order are the origin and date 
fields. 

The MIDAS Template : The MIDAS file, called FLIGHTS, has four keys, 
v*iich are defined in the following CREATK session: 
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OK, CREATK 
[CREATK rev 17.6] 

MINIMUM OPTIONS? Y^ 

FILE NAME? FLIGtfTS 
NEW FILE? YES 
DIRECT ACCESS? NO 

DATA SUBFILE QUESTIC»*S 

PRIMARY KEY TYPE: A 
PRIMARY KEY SIZE = : B 9 
EATA SIZE = : 20 

SECCMJARY INDEX 

INDEX NO.? 1 

EHJPLICATE KEYS PERMITTED? YES 

KEY TYPE: A 

KEY SIZE = : B 8 

SECCMiARY lATh SIZE = : 

INffiX NO.? 2 

DUPLICATE KEYS PERMITTED? YES 

KEY TYPE: A 

KEY SIZE = : B 5 

SECC»JDARY DATA SIZE = : 

INmX NO.? 3 

DUPLICATE KEYS PERMITTED? Y^ 

KEY TYPE: A 

KEY SIZE = : B 5 

SECCaClARY DATA SIZE = : 

INDEX NO.? (CR) 

SETTING FILE LOCK TO N READERS AND N WRITERS 

The AIRLINE Program ; The program that bulls the FLIGHTS file from the 
data in INPUT FILE is AIRLINE: 
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C 
C 
C 

c 
c 
c 
c 



AIRLINE PROGRAM 

■raiS PROGRAM BUILDS A MIDAS FILE FRCM A SEQUENTIAL DISK FILE 
USING THE OFFLINE ROUTINES PRIBLD, SECBLD AND BILD$R. 
THE PRIMARY KEY IS MADE UP OF THREE FIELES FRCM 
THE INPUT FILE AND IS THUS A CONCATENATED KEY. 



INTBGER*2 FILNAM{40) , 

+ IFUNIT, 

+ MFUNIT, 

+ PSQFLG, 

+ SSQFLG, 

+ BSQFD3(2), 

+ INmEC(20) , 

+ PRIKEY(5) , 

+ SECKEYO) , 

+ CHRP0S(2), 

+ ERRCOD, 

+ I 



/* FILE NAME BUFFER 

/* INPUT FILE FUNIT 

/* MIDAS OUTPUT FILE FUNIT 

/* PRIBLD'S SEQFLG 

/* SECBLD' S SEQFLG 

/* BILD$R'S SEQFDG'S 

/* INPUT RECCMD BUFFER 

/* PRIMARY KEY BUFFER 

/* SECOCARY KEY BUFFER 

/* POSITION SIZE ARRAY FOR TSRC$$ 

/* Emm CODE 



$INSERT SYSCQM>KEYS.F 

C 

$INSERT SYSCCM>ERRD.F 

C 

C 

C 

5 CALL TNOUA ('ENTER INPUT FILE NME: ', 23) 

READ (1, 10) FILNM 
10 FORMAT (40A2) 

CHRPOS(i) = 

CHRP0S{2) = 80 

IFUNIT = 

CALL TSRC$$ (K$READ + K$GETU, 
+ FILNAM, IFUNIT, CHRPOS, I, ERF^CD) 

IF (ERRCOD .EQ. E$FNTF) GOTO 5 

IF (ERRCOD .NE. 0) GOTO 9000 

CALL ATTDEV (IFUNIT, 7, IFUNIT, 80) /* TELL IOCS ABOUT DISK FILE 
C 

C INPUT AND OPEN THE MIDAS OUTPUT FILE. 

C 
C 
C 
C 
20 



UNIT 



NOTICE THAT (1) IT IS OPENED FOR READING AND WRITING (K$REWR) , AND 
(2) WE DO NOT (!) CALL NTFYM$ OR 0PENM$/CLOSM$ 



CALL TNOUA ('ENTER MIDAS OUTPUT FILE NAME: ', 30) 
READ (1, 10) FILNAM 
CHRPOS(l) = 
CHRP0S(2) = 80 
MFUNIT = 

CALL TSRC$$ (K$RrWR + K$GETU, 
+ FILNAM, MFUNIT, CHRPOS, I, ERRCOD) 

IF (ERRCOD .EQ. E$FNTF) GOTO 20 
IF (ERRCOD .NE. 0) GOTO 9000 
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C- 
C 



C 

C — 

C 

C 

C 

100 

110 

C 

C... 

C 

C 



— INIT SEQFDS'S 

PSQFLG = 
SSQFEX3 = 
BSQFIJ3(1) = 
BSQFD3(2) = 







/* PRIBLD SEQFDG FOR INDEX 

/* SECBLD SEQFLG FOR INDEX 1 

/* BILD$R SEQFIJ3 F(» INDEX 2 

/* BILD$R SEQFLG FOR INDEX 3 



-MAIN LOOP TO READ A RECORD FROM THE INPUT FILE AND MAKE 

THE APHROmiATE CALLS TO PRIBLD, SECBLD, AND BILD$R TO ADD THE DATA 

RECORD AND VARIOUS ENTRIES. 

READ (IFUNIT, 110, END = 500) INRREC /* READ THE INPUT RECORD 
FORMAT (20A2) 



..BUILD THE PRIMARY KEY - 

A CCMy^TENATION OF THE CBIGIN, DESTINATION, FLIGHT NUMBER. 

PRIKEY(l) = INPREC(3) 

PRIKEY{2) = LT (INPREC{4) , 8) + RS (INPREC(7) , 8) 

PRIKEY(3) = LS (INPREC(7), 8) + RS (INPREC(8) , 8) 

PRIKEY(4) = INPREC(l) 

PRIKEY(5) = LT {INPREC(2) , 8) 

CALL KilBLD (PSQFLG, PRIKEY, /* MB THE PRIMARY KEY + DATA RECORD 

+ INPREC, 20, MFUNIT, 0, 0) 



C 
C. 

c 
c 
c 
c 



c 

c. 

c 

c 

c 



,PJX> SECCNDARY KEY 1 - THE DATE. 

SINCE IT IS SC»TED, WE USE SECBLD. 

ALSO, SINCE IT IS ^ORD ALIGNED, WE DON'T HAVE TO MOVE THE 

KEY TO THE BUFFER ' SECKEY' . 



CALL SECBLD (SSQFLG, INTOECdl) , 
+ PRIKEY, 1, 0, 0, MFUNIT, 0) 



C 

C. 

C 

C 

C 



..AID SECONDARY KEY 2 - THE DEPARTURE TIME. 

IT IS UNSCKTED, SO WE CALL BILD$R AND IS UNALIGNED, SO 
WE MOVE IT TEMPORARILY TO THE BUFFER 'SECKEY' . 

SECKEY (1) = LS (INPREC (15), 8) + RS ( INPREC ( 16) , 8) 
SECKEY(2) = LS (INPREC(16) , 8) + RS (INPREC(17) , 8) 
SECKEY (3) = LS ( INPREC ( 17) , 8) 

CALL BILD$R (BSQFD3(1), /* NOTE BSQFDG(l) IS FOR INDEX 2. 

+ SECKEY, PRIKEY, 0, 0, 2, MFUNIT, 0) 



.Ar» SECCM3ARY KEY 3 - THE ARRIVAL TIME. 

THIS FOLLOWS THE SAME PATTERN OF MOVING THE KEY AND 
CALLING BILD$R AS WE DID WITH SECCM)ARY KEY # 2. 

SECKEY(l) = LS (INPREC(18) , 8) + RS (INPREC(19) , 8) 
SECKEY(2) = LS { INPREC ( 19) , 8) + RS ( INPREC ( 20) , 8) 
SECKEY(3) = LS (INPREC(20), 8) 



CALL BILD$R (BSQFD3(2), 



/* NOTE BSQFIJ3(2) IS FCH INDEX 3) 
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SECKEY, PRIKEY, 0, 0, 3, MFUNIT, 0) 

/* LOOP ON READING ADDING ENTRIES 
C 

C INPUT FILE IS EXHAUSTED. 

C SET THE SEQUENCE FLAG TO '2' AND MAKE A FINAL CALL TO THE 

C APFROroiATE ROUTINE FOR EACH INDEX BEING BUILT; THEN CLOSE 

C THE INPUT AND OUTPUT FILES. 

C 

500 PSQFDG = 2 

CALL PRIBLD (PSQFDG, 0, 0, S, MFUNIT, 0, 0) /* FINALIZE HIIMARY KEY 
C 

SSQFLC = 2 

CALL SECBLD (SSQFLG, 0, 0, 1, 0, 0, MFUNIT, 0) /* FINALIZE SECOmARY KEY 1 
C 

BSQFLG(l) = 2 

CALL BILD$R (BSQFLG(l), 0, 0, 0, 0, 2, MFUNIT, 0) /* FINALIZE SEC. KEY 2 
C 

BSQFIJ3(2) = 2 

CALL BILD$R (BSQFEC(2), 0, 0, 0, 0, 3, MFUNIT, 0) /* FINALIZE SEC. KEY 3 
C 

CALL SRCH$$ (K$CLOS, 0, 0, IFUNIT, I, ERRCOD) /* CLOSE INPUT FILE 

IF (ERRCOD .NE. 0) GOTO 9000 
C 

CALL SRCH$$ (K$CLOS, 0, 0, MFUNIT, I, ERRCOD) /* CLOSE MIDAS OUTPUT FILE 

IF (ERRCOD .NE. 0) GOTO 9000 
C 

CALL EXIT /* EXIT TO PRIMOS 

C 

C ERRCB HANDLER 

C TAKES THE BRUTE FORCE APPROACH OF CLOSING INPUT OUTPUT FILES, 

C IGNORING ANY ERRCRS ENCOUNTERED, EXITING WITH A CALL TO ERRPR$. 

C 

9000 CALL SRCH$$ (K$CLOS, 0, 0, IFUNIT, I, I) /* CLOSE INPUT FILE 

CALL SRCH$$ (K$CLOS, 0, 0, MFUNIT, I, I) /* CLOSE MIDAS OUTPUT FILE 
C 

CALL ERRPR$ (K$NRTO, 'EXAMPLE', 6, 0, 0) 
C 

END 
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Sample Output ; When the program is run, the user simply enters the 
names of the input and output (MIDAS) files and the offline routines 
take care of the rest. For example: 

OK, SEG #AIRLINE 

ENTER INPUT FILE NAME: INPUT FILE 

ENTER MIDAS OUTPUT FILE NAME: FLIGHTS 

PRIMARY INDEX AND DATA 

SECONDARY INDEX 1 

Index 0: Ehtries indexed: 7 

Index 1: Entries indexed: 7 

Index 2: Ehtries indexed: 7 

Index 3: Ehtries indexed: 7 

OK, 
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OTHER OFFLINE ROUTINES 

Several internal routines previously available only to R-iwade users in 
earlier versions of MIDAS are now generally available to all users. 
Ihey are limited in usefulness, and may appeal only to FORTRAN users 
v*io are also making use of the offline routines discussed earlier in 
this section. The routines covered here are: ERROPN, FILERR, FILHER, 
and KX$TIM. Of these four routines, tvro are still used internally by 
MIDAS: ERROFN and KX$TIM. FILHER and FILERR, no longer used by MIDAS, 
have been kept for compatibility. All of these routines are described 
briefly in I^ble 14-5. 



Table 14-5. Other Offline Routines 



Routine 



Function 



Conments 



ERROPN 



Opens a logging file to 
record errors and milestone 
statistics (see KX$TIM, 
below) 



Used by KBUILD to 
open and name 
error/logfile 



FILERR 



Sets up and writes error 
m.essages to terminal 



No longer used by 
MIDAS, but still 
available to users 



FILHER 



Converts MIDAS error code to 
corresponding text and 
passes it to FILERR 



No longer used by 
MIDAS, but still 
available to users 



KX$TIM 



Prints milestone statistics, 
including CPU, disk and wall 
clock time elapsed since last 
milestone — statistics are 
written to err/log file if 
ERROPN was called to open it 



Used by KBUILD to 
generate milestones 
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ERROFN 



ERROEW is a routine used to open an error/logging file. Its calling 
sequence is: 

CALL ERROFN (funit) 

funit is the INT*2 file unit on viiich the error/logging file is to be 
opened. It is returned as if no file was opened, tuofr ^c A ^MiA^^^' 

What It Does ; ERROPN asks the user for a pathname for the 
error/logging file with the question: 

ENTER LOG/ERROR FILE NAME: 

If you enter just a carriage return or blank line, funit is set to 
and ERROPN returns. If a valid pathname is entered, a new SAM file is 
created if necessary and opened for writing on the PRIMOS file unit 
returned in funit (via the key K$GETU) , and truncated. If an error 
occurs on the "open" call, the user is asked to enter another pathname. 
The purpose of the truncate operation is to make sure that the file is 
empty, in case the indicated file already exists. If an error occurs 
on the truncate operation, it is noted with the message: "COULEN'T 
TRUNCATE LOG/ERROR FILE" and ERROFN returns. 

Ibw ERROPN Mbrks ; Ihe file unit number (funit) on v*iich the 
error/logging file is opened is stored in an internal common area 
called /ERRFIt/. If any of the offline routines generates an error 
message, or if KX$TIM is called to print a milestone, the error message 
or the milestone is sent to the error/log file opened on /ERRFII/ as 
well as to the terminal. 

/ERRFIL/ only remembers the last error/logging file opened and does not 
notice that the user may have in fact closed the file in the meantime. 
Errors arising from attempts to write to this file are taken as a sign 
that the file has been closed and are therefore ignored. 
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On mqe 14-34 under ERRCMJ ; the tunit argiment: should always be 
2eSf!ed as a variable-iSdliot a constant, because it returns a 
value of if the call to ERKDTO is unsuccessful. 
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FILEPR 

FILERR is a user-callable routine that prints out the text of an error 
message v*iich corresponds to a code returned by one of the syston 
routines. Its calling sequence is: 

CALL FILERR (caller-name, optmsg, msglen, altrtn) 

Tfie arguments shown above, their meanings and their data types are: 

caller-name Six-character name of calling routine (INT*2) 

optmsg Optional error message to print out (INT*2) 

msglen Length of optmsg in characters (INT*2) 

altrtn Statement number of alternate return or (no 
alternate return) (INT*2) 

Haw It Wbrks ; FILERR indirectly calls the system routine ERRPR$ to 
print out the systan error message corresponding to an error code 
returned by one of the system routines. The optional message, optmsg , 
is a user-supplied message to be printed along with the s ys tem-suppl i ed 
one. Tne error code, understood to be in the variable CODE in the 
coirmon area /CODE/ (defined in KPARAM) , is translated into an actual 
error message by the internal MIDAS routine ERRTD$. The resulting 
error message, along with an optional error message (if its length is 
greater than 0), plus the caller's name, is printed out at the terminal 
and to the error/logging file if there is one in the same format as 
vrould ERRPR$. If altrtn is 0, FILERR exits to PRIMOS, otherwise it 
returns normally to the caller. 



Note 

This routine is of limited use considering that users can get 
at the common area /CODE/ only by using the unshared V-^node 
MIDAS library NVKDALB. 



FILHER 

FILHER is a user-callable routine to convert and print a MIDAS error 
code to ASCII form, calling FILERR to print it out. If you want to use 
PRIBLD, SECBLD or BILD$R, and you want to open your own error/logging 
files, all three of these internal routines should be used together. 
FILHER's calling sequence is: 

CALL FILHER (errcod, altrtn) 

errcod is an INT*2 argument representing a MIDAS error code, and altrtn 
is a user-supplied alternate return. 
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How It Mbrks ; If errcod is less than or equal to 13, or if there is a 
log/error file opened (see ERROPN) , FILERR is called with /CODE/ set to 
E$NULL (null error message) , the optional message is set to "FILE 
HANDLER ERRCR xx" , where xx is the ASCII representation of errcod, and 
the alternate return in the calling sequence to FILERR set to altrtn. 
If FILERR returns to FILHER, then FILHER returns normally to the user. 

If errcod is greater than 13 and /ERRFII/ indicates that an 
error/logging file is not open, FILHER will take an alternate return 
through altrtn or, if that is 0, it will return throigh ERRPR$ with a 
null error message. 



KX$TIM 

KX$TIM is a user-callable routine that displays milestones for the 
offline file-building routines PRIBLD, SECBLD and BILD$R. These 
milestones are displayed at the terminal and optionally recorded in an 
error/logging file opened by ERROPN. 

Its calling sequence is: 

CALL KX$TIM (numrec, optmsg, msglen) 

numrec Indicates the number of records processed for this milestone 
(INT*4). ^cial case values of and -1 make it possible to 
generate headers and so forth — details below. 

optmsg Supplied by the user only if desired (INT*2). If supplied, 
the length of optmsg, in words, must be passed in msglen . 

msglen The length of the optional optmsg , in characters (INT*2) . 
Set it to if there is no optional message. 

How KX$TIM Wbrks ; First, if there is an optional message, it is 
printed to the terminal and to the optional error/logging file. Then a 
"milestone" consisting of numrec , date and time, nuntoer of CPU minutes 
used since the last call to KX$TIM, number of disk I/O minutes used 
since the last call to KX$TIM, total CPU and disk time used so far, and 
the difference in the total since the last call, is printed in a 
similar fashion. If numrec has a value of 0, all counters will be 
initialized to and a header will be printed out before the milestone 
line. By using a numrec value of -1, a milestone of without a header 
or initialization, can be generated. 

Ebr a description of the milestones generated by KX$TIM, see Section 3. 
KBUILD itself calls KX$TIM to produce milestones during file-building. 
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ADVANCED USES OF MIDAS 



INTRODUCTIC^ 

This section is intended for users v^o are interested in modifying 
MIDAS parameters in hopes of obtaining better performance or in 
handling problems that are beyond the scope of standard MIDAS defaults. 
Users vi*io want to use the extended options feature of CREATK or to 
explore the concept of index levels will also find this section 
helpful. It also describes v*iat is in the MIDAS parameter file, 
KPARAM, and viiich parameters can be modified by the user. 



Section Tbpics 

Topics covered in this section are presented in this order: 

• CREATK' s extended options path — dialog and description 

• Double-length indexes — using the version of CREATK that 
was created by C_LCREATK 

• Adding new secondary indexes — CREATK 's AM) option 

• Altering data subfile record length — CREATK' s DATA 
option 

• Extending segment subfile length — CREATK' s EXTEND 
option 

« Modifying template parameters — CRKATK's MODIFY option 

• Modifying MIDAS defaults — KPARAM' s user-^nodifiable 
parameters 



CREATK 'S EXTENDED OPTIONS PATH 

Most users will find the minimum options path of CREATK quite suitable 
for their needs and may want to limit the amount of space allocated for 
each index subfile. CREATK's extended options path offers a way to 
alter, on a per-file basis, some of the default file parameters used by 
CREATK in initializing MIDAS files. 
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The Purpose of Extended Options 

The extended options feature of C3?EATK allows the user to specify the 
size of an index block at each index level in the index subfile. Index 
levels are described in detail under Index Levels , below. Generally, 
an index block contains key entries that point to records in the data 
subfile. An index subfile block entry includes: 

• A key value, supplied by the user during data entry (file 
building) 

• A three-word pointer to a data subfile record (in 
keyed-index access files) 

• A five-word pointer to a data subfile record (in direct 
access files) 

• Secondary data in secondary indexes (optional) 



Defining Block Size 

UrKier minimum options, CREATK doesn't ask for a block size. Instead, 
it assunes the default value of 1024 wards per block. Space may be 
wasted with 1024 words per block, depending on the average index entry 
length. Ebr instance, short files with small keys may be able to get 
by with smaller index blocks. Ch the other hand, increasing block size 
may improve access time by reducing the height (nunnber of levels) in an 
index tree. (The fewer number of levels to search, the faster the 
access time.) By modifying the block size, the user may be able to 
optimize access time and the use of storage space. 

The default setting of 1024 words per block may waste space even if 
long keys and secondary data are used. So it may be worthwhile to 
reduce block size in many cases to economize resource usage. However, 
bear in mind that search-efficiency is increased by keeping block size 
large enough to hold a maximum number of entries without wasting space. 
Such an ideal index would be "dense," with many entries packed into 
fewer levels than there would be if the block size was smaller. In 
addition, larger blocks probably mean fewer blocks. The fewer the 
blocks that MIDAS has to search throiigh, the better the performance. 
It is faster to search through one block with many entries than to 
search through many shorter index blocks. Keep in mind that 1024 wards 
is the j^iysical disk record size, and I/O is more efficient v*ien 
f^iysical and logical block sizes match. Also, if block sizes are made 
too small, frequency of block splitting can degrade performance. 



Block Size Specifications 

The block size at the first, second, and last index levels (see Index 
Block Levels , below) can be changed with the extended options version 
of CREATK. The minimum acceptable block size must be at least large 
enoiigh to hold 6 or 10 control wards and two entries at that particular 
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level. Ihe maximim block size is 32767 wrds. The minimum required 
block size varies with level: the last level index block alwa^^ has 10 
control words, v*iile upper levels have 6 control vords. CREATK checks 
to see whether or not your proposed block size will accoiranodate the 
minimum number of entries and control wards, and lets you know v*»ether 
it's acceptable. Last level index blocks also contain entry numbers if 
the file is direct access and, in secondary index subfiles that support 
the secondary data feature, last level index blocks also contain 
secondary data. This should be taken into account v*ien modifying the 
block size. 

If desired, the block size can be changed globally by modifying the 
RECLNT parameter in the KPARAM file; see MODIFYING MIDAS below. Qice 
changed, this size will be applied to every file subsequently created 
with CREATK. Itowever, existing files will retain the Block size 
specified for them vAien they were created. It is recommended that if 
the block size is changed, it should be specified as a power of 2. 
Changing this parameter, however, is not guaranteed to buy you 
anything. 



Index Block Levels 



All of the entries in an index subfile are contained in blocks, and 
each block is associated with an "index level." When space is first 

which is called the "last" level. As the file grows in size and 

complexity, more index levels are created to help maintain search 

efficiency. Blocks in these index levels are collectively called 
"upper level" index blocks. 

Why Index Levels? ; The purpose of multi-level indexing is to maximize 
search and access efficiency. The important thing to remember here is 
that only the last level index blocks contain the index entries that 
consist of key values plus pointers to record entries in the data 
subfile. 

As mentioned before, a "new" index subfile has only one level of 
indexing, the last level. At first, it contains only one block. 
Eiitries in this block point directly to the appropriate data subfile 
records. When this index block becomes full, it is split in half, 
producing two index blocks that are each half-filled. Each of these 
blocks is the same size as the original block. Another index level is 
then created above the last level index blocks. This newly-created 
"upper" index level has one block to start with, and it initially 
contains two entries that point to the blocks in the last level. When 
MIDAS searches for a particular index entry in an index subfile, it 
starts with the topmost index level and, using a search algorithm, 
follows special pointers that tell MIDAS which block in the next level 
down contains the desired index entry. As the file grows larqecr the 
index blocks at various levels will become full and must be split in a 
similar fashion. Such splitting may require the creation of additional 
index levels so that the search process will not be impaired. 
Multi-level indexing refines the search process by eliminating the need 
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for MIDAS to search through every block at each index level in order to 
find the object of the search, vhich is always located in a last level 
index block. 



Extended Options Dialog 

lb enter the extended options path of CREATK, answer "no" to the 
"MINIMUM OPTIC^rs?" prompt at the beginning of the CREATK dialog. The 
annotated dialog follows. 



Prompt 

1. MINIMUM OPTICWS? 

2. FILE NAME? 



3. NEW FILE? 



4. DIRECT ACCESS? 



DATA SUBFILE QUESTIONS 

5. PRIMARY KEY TYPE: 

6. PRIMARY KEY SIZE=: 



7. DATA SIZE=: 



Response 

Ehter N[0]. 

Ehter name of file to be 
created or name of existing 
file to be modified or 
examined . 

Enter Y[ES] . (Ehter NO to 
obtain information about an 
existing file template.) 
See below. 

Ehter Y[ES] or N[0] , 
depending on vAiether the 
direct access feature is 
desired or not. 



Ehter A,B,I,L, or S; same 
as for minimun options. 
(See Table 2-2 in Section 
2.) 

Ehter Bin or Whn, v*iere nn 
is the number of bits or 
bytes or vrords that the key 
should contain; same as for 
minimum options dialog. 

For fixed-length records, 
enter record length. 
Include the key size in this 
figure for COBOL files. 
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8. NUMBER OF ENTRIES 
TO ALLOCATE? 



Asked only if yau answered 
YES to "DIRECT ACCESS?" 
prompt above. Ehter nuntoer 
of records for vdiich to 
reserve room in the data 
subfile. 



9. FIRST LEVEL INDEX BLOCK 
SIZE=: 



10. SECCM) LEVEL INDEX 
BLOCK SIZE=: 

11. LAST LEVEL INDEX 
BLOCK SIZE=: 



Enter nianber of wards per 
block desired (default is 
1024) . See Defining Block 
Size, above. 

Should be same as above 
response . 

Should be same as above. 



SECONDARY INDEX 



12. INDEX NO? 



Indicates 
secondary 
questions. 



beginning of 
index subfile 



Enter number from 1-17, or 

simply hit (CR) if no 

secondary indexes are 
needed. 



13. DUPLICATE KEYS 
PERMITTED? 

14. KEY TYPE: 



Enter Y[ES] or N[0] 



Same as for minimum options. 
See Table 2-2 in Section 2. 



15. KEY SIZE=: 



16. SECCWDARY DATA SIZE=: 



17. FIRST LEVEL INDEX 
BLOCK SIZE=: 

18. SECOND LEVEL INDEX 
BLOCK SIZE=: 

19. LAST LEVEL INDEX 
BLOCK SIZE=: 



Returned only if A and B 
type key is specified above. 
Ehter Bin or Whn as 
described above. 

Specify secondary data size 
(FTN only) or hit (CR) . 

Ehter desired number of 
words per block. See above. 

Same as above. 



Same as above. 
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20. INDEX NO? Ehter index number from 2-17 

or hit carriage return if no 
more secondary indexes are 
needed. Prompts 13-19 are 
repeated if an index number 
is supplied. If you simply 
hit (CR) , the dialog ends, 
and this prompt appears: 

SETTING FILE LOCK TO N READERS AND N WRITERS 

If the double-length index feature has been enabled, the prompt: 

DOUBLE LENGTH INDEX? 

will appear immediately after the "SECONDARY DATA SIZE" prompt in the 
dialog above. Itouble-length indexes are described in the following 
paragrajAis. 



DOUBLE-LENGTH INDEXES 

For very large files that require index subfiles longer than the 
default of 10 segment subfiles per index, MIDAS offers the 
"double-length index" feature. If double-length indexes are desired, 
CREATK must be modified to include the double-length index request. 
There is a command file in MIDAS>SOURCE called C_LCREATK that creates a 
special version of CREATK allowing double-length indexes to be 
specified on a per-file basis. Note that the default version of CREATK 
does not ask if the user wants double-length indexes but instead 
assumes all indexes are the default length. Hawever, files created 
under a long-index version of CREATK are supported by the default 
version of CREATK. 

A double-length index, also called a "long index", is made up of two 
"regular" index subfiles that are 10 segment subfiles in length. Thus, 
each double-length index really contains 20 segment subfiles. 
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Specification of double-length indexes is selective; that is, the user 
decides v*iich indexes will be double-length and vAiich will be the 
default length. Ihis option requires a bit of caution on the users's 
part because each double-length index takes up tvro single-length 
indexes. For example, if you define the primary key as a double-length 
index, you cannot define a secondary index 1; the next available index 
would be secondary index 2. If secondary index 2 is defined as a 
double-length index, the next available index vould be secondary index 
4, not index 3. Bear in mind, however, that secondary index 17 cannot 
be defined as a double-length index or else it vould overwrite the data 
subfile segments. 



MODIFYING A TEMPLATE 

. CREATK offers four file-modification options for changing an existing 
file template. These options should be used only v*ien necessary to 
increase index subfile length, to alter the data subfile length, or to 
add a new secondary index. Although it is possible to change block 
size, secondary data size, duplicate support, and so forth, it is not 
possible to change key length or key type without recreating the file 
or index from scratch. 

These options are invoked like all the other CREATK "old file" options, 

Note 

Don't forget that any of the changes made to a MIDAS file with 
these options won't be put into effect until the MPACK utility 
is run on the file. MPACK is documented in Section 12. 



Mding Secondary Indexes 

The ADD function allows a new secondary index to be added to an 
existing file. The dialog is similar to that used in creating a 
secondary index during template creation. If the secondary index 
already exists, an error message is displayed. Remember, only 17 
secondary indexes can be defined per file. Be careful if you've 
already defined double-length indexes for the file! 



Changing Record Length 

The DATA function alters the length of a data subfile entry. This is 
the same thing as saying it alters the data size or record size in a 
MIDAS file. The DATA dialog is similar to the data subfile questions 
asked during t^nplate creaticHi. Ranoifcer, the new data size will not 
go into effect until you MPACK the file. (Use the DATA option of 
MPACK.) When MPACK is run on the modified file, existing records in 
the file will be suitably truncated or padded with 0's to make them 
compatible with the new data size. 
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Extending the Subfile 

The EXTEND function allows the user to change the length of the segment 

subfiles and the length of the segment directory i tself. The user is_ 

asked to supply the segment directory length in HMMhk-ahd the segment | 

subfile (index) length in wards. If a or (CR) is supplied, CREATK 1 

default values are used. Ihe minimum subfile size is 64K words. The 

minimun segment directory size is 185 (segments) , but this reflects a 

file with only one segment allocated for the data subfile. As the file 

grows, it will use up more segments. The current segment number at 

viiich the data subfile ends is called the "data growth point." ^ /.aA^'* * 

Modifying Other Template Parameters /V'</'*'^ 

The MODIFY function enables a user to change the following parameters 
in an existing MIDAS file tonplate: 

• Index block length (only if you're using non-^ninimum options 
path of CREATK) 

• Secondary data size - see Note below 

• Support for duplicate key occurrences 

• Changing a single-length to a long (double-length) index, 
and vice-versa (if supported by the CREATK version in use) . 
This is only permitted if you're not already using up all 
the available irxJex subfile slots. In fact, CREATK doesn't 
even ask if you want to make an index a double-length one if 
it would prove jAiysically impossible. 

If the index you're attempting to MODIFY doesn't exist, an error 
message will be displayed. 

Note 

When secondary data size is modified for a particular index, 
the existing secondary data entries will be truncated or padded 
with 0's when the file is MPACKed. This ensures that all the 
secondary data entries in that index will conform to the new 
secondary data size. 



MODIFYING MIDAS 

All of the user-modifiable MIDAS parameters are stored in the file 
KPARAM, located in the UFD MIDAS. This file contains all the 
parameters used by the MIDAS routines, but not all of them are subject 
to user modification. Modifiable parameters appear at the beginning of 
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Page 15-8 discusses the EJCTENO option of CBEMHK as a method ot 
making the index subfile longer. Bus method is preferable to the 
double-length index method *»hich can also be used to lengthen an 
index subfile. Users are urged to use the EXTQID option whenever 
they need to enlarge an index si±)f ile. Please note this carefully, 
as it was not eJ5)licitly stated anyv^ere in the book. 



Oi page 15-9, in the section on RBOUT, the third sentence *ould 
read: ■Users nay change this value depending on irtiat type of disk 
they are using." The following paragraph should be inserted 
between the two existing paragr^*is in the REXXNT secti(xi: 

The REXI2C paraneter must be large enough to ensure that each in(3ex 
block can fit two Jcey/pointer /entries plus the 10 control worsfe 
required in the last block level. However, RBCUW should not be 
given a value greater than 4095. 
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the KPARAM file, after the variable and constant declarations. The 
line separating parameters that users can modify from parameters that 
are fixed (not user-modifiable) reads: THE REMAINING PARAMETERS ARE 
FIXED. Refrain frcm tampering with the parameters that appear below 
this line, as the consequences are likely to be unpleasant. 



Effecting Qianges 

Any changes made to parameters in KPARAM require that MIDAS be 
completely rebuilt by running the appropriate coirmand files (see 
Section 13) . R-mode users and users of unshared libraries should 
reload their program runfiles with the new version of the MIDAS library 
in order to take advantage of the changes made in the KPARAM file. 
Once MIDAS is rebuilt with the "new" KPARAM file, any files 
subsequently created with CREATK will have the new KPARAM-specified 
default measurements. 



RECLNT; Index Block Length 

Ihe RECLNT parameter specifies the default index block size (length) in 
words, for each MIDAS file. As delivered, the RECLNT parameter is set 
to 1024 words. Users may §SSf^^c this value depending on viiat type of 
disk they are using. Most Prime users have storage module disks with 
default piiysical record sizes of 1024 words. Tne fxiysical record size 
is also called the physical index block size. Index block sizes should 
be specified in integral multiples or fractions of the jiiysical disk 
record size for optimal performance. 

Remember that extended options (CREATK) can be used to change the block 
size on a per-file basis. If there are only a few files for viiich the 
index block size needs adjustment, it may be easier to use extended 
options on each one than to change RECLNT and then rebuild all of 
MIDAS. If you want this change applied to existing MIDAS files, you 
can do a MODIFY on each index in every file, and then MPACK each file. 
Alternatively, you can re-create each file with the just rebuilt 
version of CREATK. 



SEGLOT; Segment Directory Length 

The length of a MIDAS segment directory is set to 512 segment subfiles. 
Every index subfile is allowed 10 segment subfiles, also called 
"segments," albeit incorrectly, and the data subfile can have up to 327 
segment subfiles, assuming that SBGLNT is set to 512. See Figure B-1 
for a representation of a MIDAS file as a segment directory. This 
parameter may be increased to allow more entries per data subfile. The 
segment directory length can also be changed on a per-file basis with 
the EXTEND option of CREATK. If you want any changef made to this 
parameter to be applied to existing MIDAS files, re-create them with 
the newly-rebuilt version of CREATK to make than compatible with the 
newly-created ones. 
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IWRAP; Segment Subfile Size 

IWRAP specifies the number of words per segment subfile. The default 
setting of this parameter is 524288 words. This segment subfile length 
enables a single file system DAM file index level to handle up to 
524288 wards (on a storage module disk only) . 

This value can be increased to allow more entries per index, or it can 
be decreased if you want to limit the number of entries that can fit in 
an index subfile. Do not set IWRAP to a value lower than 64K words. 
Increasing the value of IWRAP is a good idea if you don't (and can't) 
have double-length indexes and you need more room for entries in an 
index subfile. However, in most cases, changing this parameter will 
not alter performance significantly, so leave it alone unless you know 
v*iat you are doing. To make this change apply to files existing prior 
to the modification of IWRAP, re-create them with the newly-rebuilt 
version of CREATK. 



BREAKI; Program Interrupt Control 

BREAKI is set to a value of 1, indicating that MIDAS has control over 
when keyboard interrupts are allowed during MIDAS file processing. In 
the default break-handling method, user-initiated breaks, caused by 
hitting CTOL-P or BREAK, are disabled during calls to on-line MIDAS 
routines. MIDAS then re-enables breaks after these operations are 
completed. Users can control the enabling and disabling of breaks 
themselves by making calls to BREAK$. If BREAKS were disabled already 
v*ien MIDAS was called, MIDAS will leave them disabled \A\en control 
returns to the user. If BREAKI is set to 0, MIDAS will not disable 
breaks, viiich can be a problem, especially if a BREAK occurs during 
file update. 



RECYLA; Recycle Control 

The RECYLA parameter is of interest only to people vAio are not using 
the current method of concurrent process handling as explained in 
Section 13. Possible reasons for this might be because they haven't 
upgraded their programs intentionally or because they are operating 
over networks, in viiich case the concurrent process handling method of 
Rev 17.6 will not work. In some cases, users may not have upgraded to 
the current version of MIDAS. In any of these events, MIDAS defaults 
to the "old" method of handling simultaneous MIDAS file usage. 

Uhder the "old" method of concurrency handling, MIDAS attempts to 
change the access rights on a MIDAS file (segment directory) from "read 
only" to "read and write," in order to operate on that file. If 
another user already has the file open for writing, the attempt to open 
it for writing will fail. In this event, MIDAS will call RECYCL and 
try again. This is repeated until the attempt is sucessful or until 
the number of tries exceeds the maximum number specified in the RECYLA 
parameter (default = 1000) . The latter triggers a MIDAS error 24. 
This situation is not uncommon on systems v^iere many users are 
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attempting to access the same MIDAS file (using this "old" method) 
and/or the system is heavily-loaded in general. If MIDAS error 24 is 
occurring with troublesome frequency on your system, try increasing the 
value of RECYLA — it may alleviate the problem. RECYLA specifies the 
number of times that MIDAS should attempt to change the access rights 
before it gives up. The default setting is 1000, which should be 
enough unless the syston is overloaded or many users are working on the 
same MIDAS file. If RECYLA isn't large enoiqh, MIDAS may return an 
error code of 24. Most people will never need to adjust this parameter 
unless they access a lot of files over the network and are repeatedly 
getting a MIDAS error 24. Increasing the value of RECYLA can reduce 
the occurrence of this error. 



SHD6EG; Glared locks 

Ihe SHDSEG parameter indicates whether or not the MIDAS "lock," vAiich 
single-threads the use of MIDAS, is available. As delivered, this 
parameter is set to .TRUE., indicating that a shared data segment is 
available for the lock. The next three parameters in KPARAM indicate 
v*iere the lock is located. Netwark users can disable this lock; see 
Section 13. 



SLSEG; aiared Lock Segment 

The shared lock resides in segment :2020, as defined by the default 
setting for SLSEG. lAiless the user has some vitally important reason 
for moving the lock to another segment, this parameter should be left 
alone. Be careful when altering this value as you may wind up with 
unpleasant side-effects. There is no way to anticipate vdnat users are 
doing with various segments, so if you move the lock from 2020 to some 
other location, be sure to edit the command file C_SHAREMIDAS to share 
the new segment. Also, be careful that this segment isn't being used 
by someone else for some other purpose. 



SLWORD; Shared Lock Table Location 

SLWORD, set by default to : 177777, is the word number of the shared 
lock table. If the lock table is moved to another location, be sure 
the new location is not being used for anything else. 



MSEMAl; SemafAiore Number 

Ihe parameter MSEMAl is currently set to -16; it specifies the 
semaphore numlDer for the MIDAS lock. The semaphore is used in 
establishing a wait list for processes vaiting to obtain the MIDAS 
lock. 
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STSIZ; Files Open Between Calls 

Ihe STSIZ parameter specifies the maximum number of segment subfiles 
viiich MIDAS can leave open between calls. It is set to 20 as 
delivered, meaning that MIDAS can leave at most 20 segment subfiles 
open between one MIDAS call and the next. Previously, all segment 
subfiles were closed after each call, significantly eroding performance 
times. If performance is a problom, try increasing this 
number — performance should improve due to less file opening and 
closing overhead. Be careful, however, of making this nuntoer too 
large, or you will find yourself short of file units! The maximim 
setting for STSIZ is 128, v*iich is the maximum number of file units 
available per user. It's obvious that you'd never want to make STSIZ 
that big anyway. 



NOFUNS: Offline Routine File Units 

The NOFUNS parameter limits the nunber of file units simultaneously 
useable by the offline routines PRIBLD, SECBLD, BILD$R, KBUILD and 
MPACK. NOFUNS is currently set at 40. Some performance improvement 
may be had by increasing this number, but again, beware of 
short-changing yourself on file units by granting too many of them to 
MIDAS. 



NOLVLS; Index Levels 

NOLVLS indicates the maximum number of index levels per index subfile 
that FRIBLD, SECBLD, and BILD$R can attanpt to build during a single 
build operation. The default NOLVLS setting is 18. Based on the index 
entry size and the block size defined for each level in the index to be 
built, these utilities estimate and reserve the amount of memory needed 
to house this index on the assumption that it will have 18 levels. 
However, this space is only reserved during the index build, and any 
unused space is always freed up after the index is built. 
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APPENDIX A 
MimS ERROR MESSAGES 



INTRODUCTIOI 

Ihis appendix lists all the MIDAS error codes that the user is. likely 
to encounter during MIDAS file handling. Such errors are returned by 
internal MIDAS routines, some of vAiich users can call directly. Also 
explained in this appendix are error messages returned by KX$RFC, an 
internal MIDAS routine used by the four MIDAS utilities: CREATK, 
KBUILD, KIDDEL and MPACK. 

For information on the error messages returned by KX$CRE, PRIBID, 
SECBLD, BILD$R, KX$TIM and Other offline routines, see Section 14. 



RUN-TIME ERROR CODES 

Ihe following is a list of all MIDAS run-time error codes. Included 
for each error are: the nunijer of the error, the routines in viiich 
each is likely to occur, the cause of the error, and, in some cases, 
v^at can be done to recover frcm or avoid the error. ssSiere 
aK>ropriate, the CCeOL STATUS-CCDE equivalent is given. If the COBOL 
equivalent is missing, the MIDAS error is either not returned to the 
COBOL user at all, or, as in the case of MIDAS errors 40 and above, the 
STATUS-CODE equivalent is 99. These error codes are returned directly 
to the user unless error traps are included in the program. In each 
interface, MIDAS codes are returned to the user through different 
mechanisms. Fbr example, in CCBOL, condition codes are returned in the 
STATUS word, as a two-digit code in STATUS-KEY-1 and STATUS-KEy-2. 
FORTRAN users will recognize that these codes are returned in word 1 of 
the MIDAS communications array. 



Code Routine Explanation 

1 KX$ELP, KX$NX1 Indicates that duplicates exist for 

the current key. COBOL STATUS-CODE 
is 00. 

7 KX$NX1, KX$ESH, Indicates that the sought-after entry 
KX$EDA, KX$ELP, does not exist in the file. COBOL 
KX$GPT, KX$GNE, STATUS-CODE is 23 except in INKIXED 
KX$ULV MIDAS files opened for SEQUENTIAL 

access: CCBOL STATUS-CODE is 10 in 
this case, and 22 when a REWRITE is 
attempted without a prior READ. 
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10 



LOCKS, KX$LDR 



The data record has the "locked" 
set. CCBOL STATUS-CCBE is 90. 



bit 



11 



UPDAT$ 



12 



KX$nAD, KX$ADD 



13 



KX$CCE 



14 



20 



FINDS, UPDAT$, 
NEXT$, DELETS, 
P£D1$, LOCK$, 
GnATA$$ 



KX$WPR 



21 



22 



KX$RPR 



KX$OIT 



The data record does not have the 
"locked" bit set v*ien it should. 
This happens when an update is 
attonpted without first locking the 
record. (Method differs in each 
interface.) COBOL STATUS-CCDE is 91. 

Duplicate keys not allowed. COBOL 
STATUS-CCDE is 22 for attempt to add 
a duplicate primary key. CCBOL 
STATUS-CODE is 92 on attempt to add 
duplicate secondary key vAiere 
duplicates are not allowed. 

An unrecoverable concurrency error 
has occurred; for example, the 
user's current entry was deleted by 
another user. CCBOL STATUS-CCDE is 
94. 

MIDAS unable to obtain internal 
after call to semaphore wait-list 
manager. Also may indicate internal 
problans with use of shared lock. 
This is serious if returned 
repeatedly on a call. CCBOL 
STATUS-CODE is 94. 

Error encountered vAiile writing a 
record or index block. CCBOL 
STATUS-CODE is 30 for INMXED files, 
96 for RELATIVE files. 

Error encountered v*iile reading a 
data record or index block. CXBOL 
STATUS-CCHDE is 30 for INDEXED files, 
96 for RELATIVE files. 

Error on a call to SfK:H$$. Check 
CODE. CCBOL STATUS-CC»E is 30 for 
INDEXED files, 96 for RELATIVE files. 
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23 



24 



25 



26 



27 



29 



30 



31 



32 



33 



KX$OIT 



ADD1$ 



ArDl$ 



KX^IYB 



KX$RAD 



34 



KX$CLS, KX$CIT 



NEXT$, LOCK$, 
NEXT$$, KX$GET 



UPnAT$ 



KX$nAD, KX$IDE 
KX$IIE, KX$RIT 
KX$WIT 

NEXT$, Ar»l$, 
NE)Cr$$, KX$ESH, 
KX$EnA, BILD$R, 
KX$ULV 

NEXT$, NEXT$$ 



Error on a call to SGDR$$. Check 
CODE. CCBOL STATUS-CODE is 30 for 
INDEXED files, 96 for RELATIVE files. 

Can't open MIDAS file for reading and 
writirq after trying RECYLA times. 
(In KPARAM: default setting = 1000.) 
CCBOL STATUS-CODE is 30 for INDEXED 
files, 96 for RELATIVE files. 

An error occurred on a call to 
SRCH$$. Check CODE. CCBOL 
STATUS-CODE is 30 for INMIXED files, 
96 for RELATIVE files. 

An error occurred on a call to PRWF$$ 
while trying to read an index block. 
CCBOL STATUS-CODE is 30 for INDEXED 
files, 96 for RELATIVE files. 

An error occurred on a call to PRWF$$ 
vAiile writing an index block. CCBOL 
STATUS-CODE is 30 for INDEXED files, 
96 for RELATIVE files. In RELATIVE 
files, this happens v*ien writing a 
RELATIVE key that doesn't match the 
key as defined in the template. 

An error occurred on a call to SRCH$$ 
v*iile trying to close a segment. 
CCBOL STATUS-CCDE is 30 for INDEXED 
files, 96 for RELATIVE files. 

Ihe user did not ask for the array to 
be returned vHnen it must. Set FL$Pi:T 
in flags on the call. 

The array must be supplied but was 
not. 

User supplied a bad length, for 
example, a bad data record length. 
COBOL STATUS-CODE is 95. 

The user-supplied array is bad. 



Use of NEXT$ is not allowed in direct 
access files. CCBOL STATUS-CODE is 
97. 
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35 KXSAK) 



36 DELET$ 



42 



KX$LVL 



Cannot do an indexed add to a direct 
access file. CCBOL STATUS-CODE is 
98. 

The user set FL$USE in flags but the 
current array involved a different 
index than the one supplied by the 
user in this call. 

No offspring pointer or no next block 
found. 



44 


KX$EDA, 


KX$REC 


45 


KX$GPE, 


KX$LVL 


46 


KX$NX1 




47 


KX$DLT 




49 


KX$DLT 




50 


KX$DCD 




51 
52 


KX$ELP 
KX$GIB 





64 



CLOS$$ 



Got an index block but expected a 
data record. 

Got a data record but expected an 
index block. 

Expected duplicate key was not found. 

Attanpting to delete an entry from an 
empty block. (KX$DLT deletes index 
entries.) 



Invalid entry number; it could 
negative or out of range. 



be 



(Verflow entries discovered: for old 
files only. (Time to REMAKE the 
file!) 

Bad index pointer in index entry. 
Fbr example, segment nunber is 0. 

Index subfile overflow: too many 
segments. (Increase index subfile 
length with EXTEND, then MPACK file; 
or use MODIFY to make double-length 
indexes if your version of CREATK 
permits it. (See L_CREATK in 
Sections 13 and 15.) 



Ihable to unlock a data 
last entry referenced) 
the file. 



record (the 
upon closing 



71 



KX$DAD 



An error occurred on a direct access 
search. That is, the search was 
successful when it should not have 
been. 
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84 KX$ADD 



85 KX$AED 



Error on an attonpt to write an index 
block. The error probably occurred 
in KXSWBK, which writes the current 
block (the top entry in the access 
stack) , out to disk. May happen if 
MIEAS is unable to open or write the 
segment. 

The error actually occurred in 
KX$IIE. Either the user supplied a 
bad key length or MIDAS tried to 
insert an entry into a block that vas 
already full. This means the data 
subfile is full. 



86 KX$AIXI 



87 



KX$AK) 



An error occurred in KX$SIB v*iich 
splits index blocks. Cbuld be any 
one of many problans. 

An error occurred in KX$GNE v*iile 
attempting to get the next index 
entry. This could occur if there 
were no more entries in the index 
si±>file. 



88 KX$AIX) 



An error occurred in KX$GPE (gets 
previous entry) v*iile attempting to 
get the preceding entry. The entry 
may not exist. 



Explanation of Error Gode Numbers 






.•.>« 



wondering v*iy there 



are "holes" 



the numbering 



sequence, here is a brief explanation: 



Error code nunbers 1-13 are non-fatal errors; they will not be 
printed if your program contains an alternate return. They deal 
mainly with "find" and update errors **iich can usually be 
trapped if you take the time to write good error handlers in the 
program. 

Error codes 20-28 are disk errors and are generally fatal. They 
generate error messages that consist of a MIDAS error code plus 
a file systan message. These errors cause the program to abort, 
returning control to the user. Ibwever, they too can be handled 
in most of the language interfaces to MIDAS by including error 
traps in your programs. 



October 1980 



APPENDIX A IDR4558 



• Error codes 30-36 are file handler errors, usually generated 
v*ien arguments are supplied incorrectly to the FCFTRAN call 
level routines like MX)1$ and NEXT$. Some of them (32, 33) deal 
specifically with inmproper use of the conmunications array. 
Check all the calls to the routine in vihich the error was 
generated and fix any bad argunents. 

• Error codes 40-48 are MIDAS errors v*iich you shouldn't see. 

• Error codes 51 and 52 will only appear if you run out of room in 
a MIDAS file; at this point, you can use the CREATK EXTEND 
option to increase the segment subfile size. You must then 
MPACK the file to effect the change. See Section 15 for 
details. 

• Error codes 71-88 are mostly caused by internal MIDAS errors. 



ERRORS RETURNED BY UTILITIES 

Ihe four MIDAS utilities CREATK, KIDDEL, MPACK and KBUILD all share 
scMne common messages vAiich are returned by one MIDAS routine, KX$RFC. 
Ihis routine checks the file rev stamp to see if it is compatible with 
the current version of MIDAS. (It's a user-callable routine discussed 
in Section 14.) These utilities also check to see if the index length 
defined for the file is compatible with the INDLNT setting in the 
current version of MIDAS. 



KX$RFC Messages 

Ihe following messages are returned by KX$RFC: 

1. If a file has a major rev. stamp of Rev. 15 or earlier, the 
message : 

STOP! REMAKE THIS FILE" 

will appear. No further processing will be allowed on this 
file until the user runs the REMAKE utility. The file will 
then be compatible with MIDAS versions stamped Rev. 16 and 
above. REMAKE is now in MIDAS>CMrM:0. 

2. If the major rev stamp of the file is greater than that of the 
version of MIDAS you're currently running, MIDAS vgould rather 
not attempt any operation on the file that might endanger its 
health. Ihe warning message: 

MAJ{^ REV STAMP OF FILE GREATER THAN THAT OF MIDAS 

is displayed. The current version of MIDAS will work on any 
file with a major rev stamp lower than its own (no lower than 
Rev. 16) and will automatically update the rev stamp of the 
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file. However, it is not possible to convert back to an 
earlier major rev of MIDAS (for example, to go from 18.1 back 
to 17.4) because the above message will result vi*ien you try to 
access existing MIDAS files. It is possible to convert back 
and forth between update revs, like 17.4 and 17.6. 

3. The INDI2JT parameter in KPARAM determines the nunber of 
segments vAiich are allocated per index. The default setting is 
10. If this nunber is changed by the user (it's not supposed 
to be!), problems may arise if a file contains a number 
different than that of the current version of MIEiAS. This can 
result from a change to INDLNT in a previous version of MIDAS, 
giving all files created under that version INDLNT nunnber of 
segments per index. When a new version of MIDAS is installed, 
with INDLNT set to 10 (by default) , problans will arise. The 
same result occurs if you change INDLNT in the new version of 
MIDAS, making it different for the INDLNT value contained in 
existing files. In either case, the following message is 
returned : 

BASIC INDEX LENGTH OF FILE DOES NOT MATCH THAT OF MIDAS 

If INDIM" has been changed in the current version of MIDAS, 
change it back to a value compatible with the INDIM" setting in 
the file or recreate all your old files with the new version of 
MIDrS, ensuring that they are all built the same way and can be 
properly used by all the current MIDAS utilities. 

4. If the file name passed to a utility is not that of a MIDAS 
file, KX$RFC returns the error message: 

NOT A VALID MIDAS FILE (caller-name) 

v^ere caller-name is the name of the routine that called 
KX$RFC"^ This can happen if: 

• the named file is not a SAM segment directory, 

• if segment subfile (the file descriptor subfile) is not 
present, or 

• if segment subfile does not contain the proper 
information to indicate that it is a MIDAS file. 



KX$OIT Message 

Another message, returned by the KX$OIT routine (v*iich is called by 
every routine that wants to open an index subfile for update) , occurs 
if KX$OIT is unable to open the file, either because it does not exist 
or because the use of this index is not supported by the access method 
being used. 
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The following message is returned: 

Segdir unit not open. {KX$OIT) 

UNABLE TO VERIFY/UPDATE MIDAS REV FOR INDEX XX 

v*iere xx is the number of the index subfile v*iich KX$OIT tried to open. 

This can happen in COBOL, for example, if a direct access file is 
opened for indexed access and the user tries to access the file by 
secondary key. The program will fail viien KX$OIT attempts to open the 
secondary index subfile because secondary keys (and indexes) are not 
supported by RELATIVE file structure. 

This message can also happen if you are trying to access an index that 
doesn't exist. 
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APPENDIX B 
MIDftS AND WE FILE SYSTEM 



FILE SYSTEM BACKGROUND 

For those users familiar with the PRIMOS file system, this appendix 
explains how MIDAS file structure is related to file types yDU already 
know. Those not familiar with Prime file structure will probably find 
enoigh information here to make sense out of the sitisequent discussion 
of MIDAS file structure. See The Subroutine Reference Guide for more 
information on Prime file structure. 



Sm Files 

Most files under PRIMOS are structured for sequential access, and are 
called "sequential access method", or SAM, files. Iheir records are 
"strung together" by forward and backward pointers. Td get any record 
in a SAM file, you must step sequentially through the file records 
until the desired one is found. You cannot randonly retrieve any 
record in the file; but it is possible to get back to the beginning of 
the file to reprocess it. From the user's viewpoint, records in SAM 
file do not have to he the same length; hence they are called 
"variable-length" records. Ihe file systan, however, stores SAM files 
in IK word records (1024 words) . See Figure B-1 for a picture of SAM 
file structure. 



DftM Files 

DAM files are basically SAM files with an extra set of pointers stored 
in a separate index. DAM files are also called "random" files because 
records can be accessed randomly in any order, ibvievet , to get a 
particular record, you have to know something about it, like its 
starting address. From the file system's viewpoint, every record in a 
DAM file has to be the same length so the starting and ending positions 
(address) of each are known. This makes random access possible. 
Figure B-2 shows the logical structure of a simple DAM file. It should 
be noted that the forward^aackward inter-record pointers like those in 
a SAM file also exist in DAM files so that records can be accessed 
sequentially also. 
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POINTER TO DIRECTORY 
IN WHICH THIS FILE IS 
LOCATED 



• ' 


FORWARD ^ 

"roiBTlR ^ 

^ BACKWARD 






« 




^ 


, « 


DATA 
1024 
WORDS 


^ POINTER 


DATA 




DATA 



FIRST 
RECORD 
IN FILE 



LAST 
RECORD 

IN FILE 



SAM File Structure 



NOTE: 

NON-ZERO INTER-RECORD POINTERS 
ARE INDICATED BY ARROWS AND 
DOTS (.); POINTERS WITH ZERO VALUES 
ARE INDICATED WITH A "•" AND 00 NOT 
REFERENCE, OR POINT TO, ANYTHING. 



Figure B-1. SAM File Structure 
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DIRECTORY 




FWD/BKWO LINKAGE IS MAINTAINED 
FOR SAM FILE ACCESS IF REQUIRED 







DATA 








Figure B-2. Simple DAM File Structure 
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Multi-Level DAM File Structure 



The DAM file structure represented in Figure B-2 is a "short" DAM file; 
it only has a single-level index to the data records in the file. All 
the individual record pointers are contained in that index level. For 
larger files, one index level would neither be sufficient nor efficient 
for quick look-up, and, after all, that's the purpose of direct access 
files. More index levels have to be created, making one index level an 
index to the next index level and so on. Figure B-3 shows a three 
level index structure for a DAM file. MIDAS uses this multi-level 
index concept in a similar fashion to implement its index subfile 
structure . 



Segment Directories 

In PRIMOS terms, a MIDAS file is a special collection of both SAM and 
DAM files, called a segment directory. A segment directory can be 
thought of as a network of files, all related and connected by pointers 
v*iich ultimately reference entries in a data file. Think of it as a 
large city, like New York, vAiich is divided into several "boroughs" 
like Manhattan, Brooklyn and the Bronx, but is technically a single 
city. 

A segment directory is a large file similar to a directory (sub-UFD) . 
Its "subordinate" files are not referenced by name as in a sub-UFD, but 
by number . Refer to Figure B-4 for a picture of a MIDAS file viewed as 
a segment directory. The various files in a segment directory are 
called segment subfiles and consist of one or more segments. There are 
at least four types of segment subfiles in any MIDAS segment directory: 

• A file descriptor subfile 

• A primary index subfile 

• From 1 to 17 secondary index subfiles 

• A data subfile 

Below is a description of each of these subfiles. 

The File Descriptor Subfile ; The first segment in a segment directory 
(which is segment 0) is the file descriptor subfile . This is nothing 
more than a list of all the other index subfiles associated with a 
particular segment directory. It is essentially an overview of the 
entire segment directory's structure. Any time the structure of an 
index subfile or a data subfile is changed, the modifications are 
reflected in the descriptor subfile. This ensures that the description 
of the file matches the actual state of the file at any given time. 

The Data Subfile: The data subfile is the "core" of the MIDAS file. 
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UfD 
DIRECTORY 



TOP LEVEL INDEX 




DATA 
SLOCK 
> 

(1024 WORDSI 



FORHARO/BACKWARO 
POINTERS ARE MAIN 
TAINED BETWEEN DATA 
BLOCKS 



Figure B-3. Multiple Level Index DAM File 
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SEGMENT 
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SEGMENT 







SEGMENTS 
1-10 






SEGMENTS 
11-20 






• 
• 
• 




SEGMENTS 
171-180 






• 
• 
• 




SEGMENTS 
185-n 







FILE DESCRIPTOR SUBFILE 



PRIMARY INDEX SUBFILE 



SECONDARY INDEX SUBFILE #1 



t 



SECONDARY INDEX SUBFILES #2-16 



\ 



SECONDARY INDEX SUBFILE #17 



DATA SUBFILE 

n = 511 (DEFAULT MAXIMUM) 



Figure B-4. Segment Directory Structure 
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It contains the actual data that we want to look up, report on, modify, 
and so forth. Every record in the data subfile is referenced or 
pointed to by an entry in one or more of the index subfiles associated 
with that particular MIDAS file. 



The Index Subfile : Every MIDAS file has at least one index subfile, 
the primary index subfile, and up to 17 secondary index subfiles. Each 
index subfile consists of one or more segments. Ihe first segment, 
called an index descriptor block , is a guide to the index subfile and 
includes the root index block. It tells MIDAS v*iat's in the remaining 
segments of the subfile. These segments contain index blocks . The 
number of index blocks per segment depends on the length of the 
segment; the default value is 512 blocks per segment. However, this 
can be modified by using the EXTEND option of CREATK. See Section 15. 



The Index Block ; Each index block contains many entries. Each entry 
consists of a key-field value (from the data file) plus a three-word 
pointer to either another index block in the subfile, or to an entry in 
the data subfile. At the beginning of every index block is information 
six:h as key type and length; this information is used in looking up a 
particular key entry in that index block. Indexes have a hierarchical 
structure governed by the B-tree algorithm as explained in Section 15. 
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CBSOLETE MATERIAL 



INTRODUCTIOJ 



This appendix summarizes all the MIDAS routines that are no longer 
available or are no longer supported. Users of past versions of MIDAS 
should carefully remove any calls to obsolete routines from their old 
programs. More information on things that have changed in MIDAS from 
the previous revision to the present one is available in ^pendix D. 



CBSOLETE MATERIAL 

For your convenience, the obsolete material is divided into three 
parts: 

• Obsolete conunand files 

• Cbsolete routines 

• Effectively obsolete material 

Make sure any obsolete conmand files or calls to obsolete routines are 
taken out of all existing user conmand files and application programs, 
as they will not work with the new version of MIDAS. 

Cbsolete Cbmmand Files 

The following command files have been obsoieted: 

• C_FORM: was formerly used to produce an R-mode library with 
in-line desectorization to help out memory-cramped users with 
both MIDAS and FORMS running simultaneously. Ihe new interlude 
alleviates this problem. 

• C_NDA4: generated a V-mode library without direct access 
support; designed for memory-cramped users — similar to 
C_FORM. There is no penalty if the user has VKDALB configured 
for direct access but does not use it. In files that do use 
direct access, there is a two-word overhead per primary ^key 
entry. See Note , below. 

• C_NODA: was used to generate an R-mode library without direct 
access support. With the new V-mode interlude in place, the 
R-fflode library tracks the V-mode library for presence or absence 
of direct access support making this file unnecessary. 
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• C_SPCR: generated a special version of CREATK called SPCR. 
Both C_SPCR and SPCR are now obsolete. 

• C_MINIT and C_MSHAR: have been replaced by C_SHAREMIDAS, which 
shares the MIDAS library, the MIDAS shared lock segment, and 
intializes everything by running SYSTEM>IMIDAS. 

• C FILL: has been replaced by the C_LIST_MIDAS conmand file 
vhich creates a listing of MIDftS called MIDAS>SOURCE>L_MIDAS. 

Note 

If users of MIDAS libraries created by either C_NODA or C_NnA4 
opt for the default version of the V-tnode library, tvro changes 
will be apparent: 

1. CREATK will ask if the file being created is to be 
direct access or not. 

2. Direct access calls will no longer produce errors. 

Obsolete Routines 

Ihe following routines are no longer included in MIDAS: 

FILSET 

KX$BWT 

KX$PCL 

KX$01X 

PRIRAN 

SECRAN 

SYSINI 

Ihe functionality of SECRAN and PRIRAN has essentially been taken over 
by BILD$R (processes unsorted data) and therefore, it is no longer 
necessary to keep them alive. Users v*io previously used PRIBLD, SECBLD 
and BILD$R will note that FILSET has gone away, meaning that if you 
haven't already done so, it's time to change all the calls to PRIBLD, 
SECBLD and BILD$R in existing programs. See Appendix D and Section 14 
for details. 

Note 

The $INSERT file OFFCOM has been removed from MIDAS and should 
no longer be included in an^ application programs. 
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Lesser-Known Obsolete Rautines 

A few miscellaneous routines have crept into MIDAS over the years v*iich 
most users have never heard of; however, those users vrfio have 
incorporated them into their programs (FORTRAN or PMA) will want to be 
aware of their absence from this version of MIDAS. They are; 

• OPEN$ ; User callable routine formerly used to open a MIDAS 
segment directory: it should not be confused with 0PEI*1$:, 
currently used to open a MIDAS file. 

• CLOSE$ ; Obsolete user callable routine used to close a MIDAS 
segment directory: the companion routine of OPEN$:. Do not 
confuse it with CLOSM$, vAiich is the routine currently used to 
close MIDAS files under the new concurrent process handling 
method. 



EFFECTIVELY OBSOLETE MATERIAL 

Some command files and routines now considered obsolete or frozen, 
appear in the current version of MIDAS for those users vrfio have 
recently been converted from a Rev 15 (or earlier) , or for those users 
viho have files created under an ancient version of MIDAS. 



Maintained for Compatibility 

Below is a list of effectively obsolete routines, still available for 
use, but not highly recommended for such: 



C_REMAKE: compiles and loads the obsolete utility REMAKE, 
producing an executable version of REMAKE in MIDAS>CMI»JC0. 
Since RPW-AKE comes already built in the MinAS>CMENC0, users 
won't have much use for this command file. REMAKE should only 
be used by users converting pre-Rev 15 files to run under a 
later version of MIDAS. REMAKE used to be a resumable file 
called *REMAKE. 

C_REVERT: compiles and loads the obsolete REVERT utility, 
placing it in MIDAS>CMnMC0. It is unlikely that anyone will be 
using REVERT except in rare cases where it is necessary to 
convert files to run on previous versions of MIDAS. REVERT 
comes already built in MIDAS>CMDNC0, so there's no need to run 
this coirmand file unless you delete the existing version of 
REVERT. Note also that REVERT used to be a resumable file 
called *REVERT. 
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UMCDE$: is another routine still present in MIDAS, and 
formerly used in many aH>lications, v*iich signals single or 
multi-user mode. It has been obsoleted by the new method of 
concurrent process handling and should not be used at all under 
the current version of MIDAS. 



Maintained, But Not Ehthusiastically 

The secondary data feature has been maintained in this version of 
MIDAS; however, its use is not encouraged. Most people used it to 
"hide" data in the secondary index, along with a secondary key value. 
Ibwever, if data is this sensitive, perhaps you ought to be using POWER 
or MMS to protect it. Although useful if properly implemented, the 
secondary data feature has generated a lot of confusion among users and 
needlessly complicates file modification and recovery. At this point, 
users with secondary data are not being forced to remove it, but its 
use in new MIDAS files is not condoned. 
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APPENDIX D 
THE MIDAS ARCHIVES 



INTRODUCTIOI 

Ihis a^Jendix is meant only for MIDAS users v*io have used it in the 
past and want to know what must be changed or deleted in their 
application programs and command files. New users of MIDAS needn't 
bother with this unless they are curious about the historical 
development of MIDAS. 

Basically, the information in this section covers these general areas: 



• Administrative and installation changes 

• Changes in certain methodology for this version of MIDAS 

• Changes to utilities and routines that require program 
modification 

• Additions to the repertoire of MIDAS routines and command files 



AEMINSTRATIVEyiNSTALLATION CHANGES 

Installation and administrative modifications involve changes to MIDAS 
conmand file names and functions, and functional changes in the IMIDAS 
and MCLUP utilities. 



Command File Changes 

Below is a summary, in list form, of the major changes that have 
occurred to MIDAS in the administrative and installation areas at this 
revision. Many of these changes will directly impact some user command 
files, especially if the coimand files are used routinely in 
initializing and reloading MIDAS. 



• MIDAS>C_MIDAS no longer calls MIDAS>SOURCE>C_REMAKE or 
MIDAS>SOURCE>C_REVERT. Both MIDAS>CMENC0>REWAKE and 
MIDAS>CMDNC0>REVERT come already built on the master disk and 
most users will never need to rebuild than. 

• MIDAS>C_INSTALLMIDAS does not copy MIDAS>CMWC0>REI«yiiKE or 
MIDAS>CMDi«:0>REMAKE to the system UFD CMIM:0. HDwever, it does 
copy MIDAS>CMDNC0>MPACK to CMDtKie, 
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MIDAS>SOURCE>C_FILL has been changed C_LIST_MIDAS, also in 
MIDAS>SOURCE. It produces a listing of MIDAS called L_MIDAS in 
MIDAS>SOURCE. 

MIDAS>SOURCE>C_MPACK now produces MIDAS>CMDNC0>MPACK rather than 
MIDAS>SOURCE>*MPACK. 

MIDAS>SOURCE>C_MSHAR and MIDAS>SOURCE>M_INIT have been replaced 
by MIDAS>C_SHAREMIDAS v*iich does everything the former conmand 
files did, plus it runs IMIDAS. 

MIDftS>SOURCE>C_REMAKE now produces MIDAS>CMDNC0>REMAKE instead 
of MIDAS>SOURCE>*REMAKE. See Appendix C for more information. 

MIDAS>SOURCE>C_REVERT now produces MIDAS>CMENC0>REVERT instead 
of MIDAS>SOURCE>*REVERT. See also i^pendix C. 



Changes to Administrative Utilities 

Both the IMIDAS and MCLUP utilities have been changed at this revision 
of MIDAS to improve MIDAS initialization and clean-up. 

IMIDAS Changes ; IMIDAS initializes the shared lock and sanaphore for 
single-threading MIDAS use. At this revision of MIDAS, IMIDAS can only 
be run from the system console. If any other user attempts to run. it, 
this message appears: 

IMIDAS MUST BE RUN FROM THE SYSTEM COISOLE (IMIDAS) 

Make sure that no one else is using MIDAS vAien the IMIDAS utility is 
run, or that person's opened MIDAS files may be corrupted. 

MCLUP Changes ; Although breaks are inhibited during most of a MIDAS 
call, it is still possible for a MIDAS user, vAiether by forced-logout 
or by breaking out of a program via CTRI/P/ to exit MIDAS before the 
next process on the wait list can be notified that the lock is free. 
In this case, the user who quits out of MIDAS does release the lock, 
but simply doesn't get a chance to generate the usual "notify" to the 
sema0iore wait list. The "notify" triggers the next process on the 
list to attonpt to obtain the lock. Ihis doesn't happen often, but 
v*ien it does, all MIDAS operations come to a halt. All MIDAS users on 
the semaphore wait list will sit idle, waiting for the notify that 
never came. 

Previously, the only recourse in this situation was to run IMIDAS from 
the system console. MCLUP, observing that the lock did not contain the 
user nunber of a person owning the lock, could do nothing. Now, when 
the lock is set to zero, indicating that it is free, and the sonaphore 
wait count is negative, indicating one or more users waiting on the 
semaphore, MCLUP will assume the situation outlined above has occurred 
and will generate a notify to the sema^iore. However, this will only 
happen if someone ranembers to run MCLUP v*ien MIDAS goes out of 
commission. 
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After generating the notify, MCLUP will print this message: 

Cleanup for unknown user successful 
at the terminal of the user who invoked MCLUP. 

Changes to KPARAM 

Ihe KPARAM file, v*iich contains all the parameters used by MIDAS 
routines, has been modified at Rev. 17.6 to "fix" several formerly 
user^nodifiable parameters. Ihis means that users who have previously 
modified the following parameters will be unable to modify them from 
now on: 

• INDLNT 

• INDNUM 

• MFILES 

• MKEYSZ 

• NFUNIT 

SMniai n?Q 

• NOIDXS 

Ihis should prevent users from making inappropriate changes to these 
parameters and thus getting into trouble. In most cases, it WDuld not 
buy users a great deal to modify them anyway, as these parameters have 
already been set to achieve the maximum level of performance. 
Parameters which users can currently modify are explained in Section 
15. 

NEW METHODS AND OLD METHODS 

The new version of MIDAS incorporates two new methodologies for 
handling old problems. Ihese new methods involve concurrent process 
handling and the elimination of R-^node processing via the new R-mode 
library interlude. 
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Ihe R-Mode Interlude 

At this revision of MIEAS, the runtime routines in the R-mode MICAS 
library, KIDALB, have been replaced by an interlude to the V-mode 
library. This was done primarily to: 

• Reduce manor y requiranents. Instead of xx copies of the R-mode 
runtime routines for 5qc users, there will be just the one shared 
V-mode MIDAS library copy (VKDALB) and xx copies of the much 
smaller interlude. 

• ^ed up I/O time by using all V-mode calls which are much 
faster than corresponding R-inode calls. Since one MIDAS call 
typically generates many system calls, the impact should be 
noticeable. 

There is no need to reload R-mode programs using just the MIDAS library 
if a new copy of the V-mode MIDAS library is brought up. Because the 
library is dynamically linked with every execution, R-mode programs 
will need only to be reloaded once to use this new library and never 
again unless programs are saved after being run — a rather uncommon 
practice. 

Obviously, this interlude will not Viork on a P300. 

Related Changes ; The interlude brings with it several other changes 
v*iich have been mentioned briefly in other sections, but v*iich are 
gathered here to provide an overall summary: 

• The R-mode library will now track the V-mode library both in the 
presence or absence of direct access support. 

• E3RR0BI, FILERR, FILHER, and KX$TIM will be the only internal 
MIDAS routines callable by V-mode and R-^node users. Previously, 
V-mode users had access to no internal routines at all. Since 
the R•^node library tracks the V-mode library in functionality, 
calls to internal routines have to be restricted. Several 
routines have been dropped because of this, including FILSET, 
KX$BWT, KX$FCL, KX$OIX, PRIRAN, SECRAN, and SYSINI which have 
all been obsoleted or duplicated in functionality elsev*iere in 
MIDAS. 



Concurrent Process Handling 

The new method of concurrent process handling involves new open and a 
close routines, a shared lock and semaphore wait list v*iich 
single-thread MIDAS use. The current method improves MIDAS performance 
significantly by reducing file system overhead. It may be helpful to 
summarize how MIDAS previously handled concurrent access before 
explaining how the new method works. 



REV. D - 



im4558 THE MIDAS ARCHIVES 



Previous Concur rency-Handling Methods ; In previous releases, MIDAS 
coordinated concurrent processes by gating processes at the segment 
subfile (MIDAS file index) level. This method relied upon file system 
read/write locks, v*iich were previously set at 2, and required that 
segment subfiles be opened at the start of each MIDAS file operation 
and be closed upon completion of that operation. 

With this method, only one process could access a file segment at a 
time. A second process could only proceed after the first process 
finished its MIDAS operation and the file segments were closed. This 
method of synchronization required many calls to the file system 
routine SRCH$$ to open and close file segments, thus imposing a 
significant performance penalty. 

fbr example, to retrieve a record, MIDAS opened the index segment 
subfile (s) and the data segment subfile. When the retrieval was 
completed, MIDAS closed these segment subfiles. This was repeated for 
every operation on a MIDAS file, resulting in substantial disk I/O 
overhead during sequential processing of large files. 

The New Method 

MIDAS 's present method of handling concurrent processes improves 
performance by greatly reducing the number of file system calls. By 
using a sema^iore and a "lock" in shared memory, MIDAS simply allows 
only one process at a time to execute a MIDAS file operation. 
Therefore, MIDAS segment subfiles need not be closed at the end of each 
operation only to be reopened at the start of the next call, as was the 
case in the old method. See Section 13 for details. 

For FORTRAN/PMA Users Cttly ; This method also requires that the user 
open and close MIDAS files with one of two methods, described in 
Section 6. These methods use either the OPEM$ and CLOSM$ routines, or 
the KiTFYM$ routine, all of which are recent additions to the MIDAS 
repertoire. Section 6 tells you how to use them. See also NEW 
ROUTINES below. 



CHANGES TO EXISTING ROUTINES 

Some routines have been rewritten and/or have had their calling 
sequences changed. Make sure you make the appropriate adjustments in 
your programs. 

Changes to Offline Routines 

The offline file building routines PRIBLD, SECBLD, and BILD$R have been 
rewritten for 17.6 in V-mode. This was done to make better use of file 
units by leaving them open between calls, redixre disk usage through a 
different index build algorithm, and generate more useful diagnostics. 
User application programs calling these routines will have to be 
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changed to agree with the new calling sequences, taking care also to 
delete $INSERT SYSC0M>OFFCCM statements from all programs because 
OFFCOM no longer exists. You should also delete calls to FILSET, 
KX$BWT, KX$FCL (v*iich are all obsolete) , and any calls to the file 
system to open the MIEAS file descriptor subfile on some file unit 
specified by ISUNIT. ISUNIT no longer exists either. The j temps 
argisnent, a three-word array formerly used in all calls to these 
offline routines has been replaced by an INT*2 sequence flag. Details 
on the sequence flag can be found in Section 14. 

Calls to PRIBLD, SECBLD and BILD$R may still be made from the same 
program to build different indexes at the same time, but these indexes 
must all belong to the same MIDAS file. Indexes from different MID;^ 
files cannot be built by these routines by the same program at the same 
time. 

PRIBID, SECBLD and BILD$R are now able to build both output files with 
variable-length data records and direct access MIDAS files. See 
Section 14 for the new calling sequences for these routines and a list 
of the new error messages they generate. It should be noted that vrfien 
one of these routines returns an error message other than the ones 
listed in Section 14, it is almost guaranteed that the file being built 
will be useless. In this case, it is suggested that the user zero the 
file (use KIDDEL) , try to figure out v*iat went wrong and try again. 



Changes to FCHTRAN Subroutines 

No new MIDAS subroutine calls have been added to the FC^TRAN/PMA 
interface, but the file-no parameter, present in the general calling 
sequence as represented in the old MIDAS manual, has been obsoleted. 
See the new calling sequence in Section 6. Also an addition to the 
MIDAS flags parameter, v*iich some users may already know about, was 
made, allowing users access to the index entry immediately prior to the 
current one. This is done by setting bit 11 in flags, called FL$PRE. 
See Section 6 for further information. 



Changes to Utilities 

All of the MIDAS utilities have been modified for this version of 
MIDAS. Some of the dialogs have changed significantly, producing 
different prompts and sometimes in new sequences; others have changed 
internally, with little impact on the responses required of the user. 
The utilities that have been changed in a major user-visible way are 
discussed here, with additional information available in other sections 
of this book as indicated. Users should read this information 
carefully and make the appropriate changes to any command files that 
invoke these utilities. 
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uianges to ckEAxK 

CREATK and all of its subroutines have been rewritten. CREATK must now 
run in in V-^node. User input to prompts is checked as thoroughly as 
possible, and error messages, vAiere they appear, are considerably more 
informative than in previous versions. 

Sumnary of Enchancements and Alterations ; Althoi;gh the rewrite of 
CREATK attempted to maintain a high degree of compatibility (for the 
sake of veteran users with a plethora of command files) , some 
unavoidably incompatible changes were forced by the adoption of B-trees 
at rev 16.5. The list below surtmarizes all of CREATK' s major 
user-visible changes, most of v*iich were not specifically addressed in 
Section 2 to spare new users additional trauna. 

• lowercase input is now accepted; in fact, a mixture of upper- 
and lowercase input is fine. 

• Questions requiring a yes/no type of response will not accept a 
carriage return or blank line as a valid reponse. Such 
questions will accept "YES", "NO", "AYE", "NAY", or "OK" in 
upper, lower, or mixed cases. 

• Treenames (also called "pathnames") are now accepted in place of 
filenames, if this has not been stated previously. 

• Hard-wired file units have been eliminated. 

• When creating a new file, CREATK now asks for "PRIMARY KEY TYPE" 
and "PRIMARY KEY SIZE" instead of "KEY TYPE " and "KEY SIZE ." 
Ihe messages for secondary indexes remain unchanged. This 
should make things clearer for new users. 

• Ihe key size scanner is now more lenient and does better key 
size checking. The maximum key size is 16 words (32 bytes or 
256 bits) for bit strings, and 32 words (64 bytes) for ASCII 
strings. Integer and floating-point key types ronain predefined 
by the hardware. 

• If the file, v^ether a new one under creation or an old one 
being modified, is enabled for direct access, the number of 
records specified by the user to be pre-allocated is checked to 
make sure that: (1) it is greater than 0.0, (2) it is a v*ole 
ntffiiber and (3) it can actually be pre-allocated given the file's 
maximum segment directory size and maximum number of words per 
segment. 

• Secondary index numbers greater than 17 are not accepted. If 
secondary indexes 18, 19 and 20 existed, they would overlay part 
of the data segment subfiles. 
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• If you are using a version of CREATK that allows double-length 
indexes (i.e., one that was created by L_CREATK) , the new 
version of CREATK will not allow index nunber 17 to be double 
length. This, too, would overlay part of the data segment 
subfiles. 

• The user provided secondary data size is checked to make sure 
that at least two index entries can be inserted in a last level 
index block. In case of an error, the maximum secondary data 
size for that index is printed, given the maximum index block 
size defined by the parameter RECLNT in MinAS>SOURCE>KPARAM, 
normally set at 1024 words. 

• The user-specified block size for the extended options path is 
checked to ensure that at least tvo index entries can be 
inserted per index block on that level. Ch error, the minimum 
block size for that index at that level is printed. Ihe maximum 
is- assimed to be defined by the parameter RECLNT in 
MIDAS>SOURCE>KPARAM, normally 1024 words. 

• Ihe key size is no longer requested at each index block level in 
the extended options path. With the advent of B-trees, the 
index key size is assumed to be uniform through all levels of an 
index B-tree. 

• Previously, if running a version of CREATK with double-length 
index support enabled, the query "DOUBLE LENGTH INDEX?" was 
asked before the primary key type and key size were requested, 
and after the key type and key size for each secondary index 
were requested. CREATK now uniformly queries the user after the 
key type and size have been entered, regardless of whether the 
primary or secondary index is being defined. 

• The file read/write lock is set to n readers arK3 n writers on 
file creation by default. CREATK informs the user of this by 
displaying the message "SETTING FILE LOCK TO N READERS AND N 
WRITERS" at the end of each file creation session. You can have 
CREATK set the file read/write locks to the system default 
setting, usually n readers and one writer, by substituting the 
key M$NR1W for M$NRNW in the call to KX$CRE in CREATK (MAIN) . 

• A new file is not created until all the questions necessary to 
define a template have been answered properly. A user may 
therefore break (CTRE/P) out of CREATK any time before this and 
not end up with a partially created file. 

• If a file system error is encountered, CREATK responds in a 
reasonably polite manner, telling you v*iat the file system error 
is instead of just giving you a MIDAS error code. If the error 
occurs while creating a new file, CREATK, through KX$CRE, 
attempts to delete the partially created file and reports the 
original file error, ignoring any errors it may have encountered 
v*iile attempting to delete it. If the file system error occurs 
while processing an already existing file, the file(s) are just 
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closed and the original error is reported with errors 
encountered in closing ignored. 

• When you ask to work on an already existing file, MIDAS examines 
it carefully to see that it is indeed a valid MIDAS file. The 
routine KX$RFC, documented in Section 14, is called to do this 
verification. See Appendix A for messages commonly returned by 
KX$RPC. 

Changes to CREATK Options ; The following changes apply specifically 
to the various options of CREATK that have been changed in this version 
of MIDAS. 



The EXTEND option now checks the user-specified segment 
directory size to ensure that it is not smaller than the current 
data file growth point. If it is, the message "ALREADY USED 
THROUGH SEGMENT nnn" is displayed, v*iere nnn is the data file 
growth point, and the question is re-issued. As before, a 
response to either question of the extend options dialog causes 
CREATK to assume the default sizes. The minimim segment subfile 
size is still 64K words. See Section 15 also. 

The LUSAGE command is no longer displayed as a valid function by 
the HELP command. Ihe LUSAGE ccaranand is still supported, that 
is, you can still use it, but it does the same thing as the 
USAGE command. Previously, the only difference between the two 
was that LUSAGE also printed the version of MIDAS that last 
modified the file. Both coiranands now do this and LUSAGE is 
being de-emphasized to avoid confusion. 

The MODIFY function no longer exits to Primos upon receipt of a 
carriage return or blank line for an index number. Instead, it 
will return to the question "FUNCTION?", making it consistent 



Vvhen MODIFYing a double-length index, CREATK will first check to 
see v^ether the index already contains enough entries to to 
cause it to overflow a normal index. This means it would now be 
using the additional space available in a double-length index. 
If so, MODIFY will not ask v\^ether the index should remain a 
double-length one or not; it is assumed that the index must 
remain a double-length index, preventing the user from trying to 
create a new index on top of the already existing long index. 
MODIFY will ask if an index is to remain a double-length index, 
regardless of v^iether your version of CREATK supports 
double-length indexes or not, only if the index already is 
double-length and the index is not using its extra space yet. 
MODIFY will not ask if an index is to become double-length if 
the index following it already exists, or if the index in 
question is secondary index 17, or if the running version of 
CREATK is not enabled to ask about double-length indexes. 
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• The PRINT and SIZE functions always print the key size in words 
and bits or bytes now. Previously, if the key type was integer 
or floating point, the key size was printed in words only. 

• Ihe PRINT function, v*ien giving statistics about index "DATA"" 
(the data subfile) , will print "PRIMARY KEY SIZE" rather than 
"KEY SIZE" to distiguish v*iich index data key size is being 
printed. Users are rsninded that the number of entries printed 
for index "DATA" are the nunber of entries as of the last MPACK 
of the file. 

• Ihe VERSI(a>I function does not make reference to overflow blocks 
or overflow chains anymore. The v*K»le concept of overflow was 
eliminated with the advent of B-trees at rev 16.5. 



Changes to KIDDEL 

KIDDEL has been rewritten to run in V-mode, and now accepts the use of 
pathnames, does not use hard-wired file units, and can zero 
(initialize) as well as delete the various parts of a MIDAS file. 

Sumnary of Changes : Instead of asking the single question: 

INDICIES? 
KIDDEL now asks the following question: 

DELETE INMIXES: 
The user may answer with one of the following responses: 

• A list of index nvmbers to be deleted — this deletes just 
certain index subfiles 

• ALL — which deletes entire file 

• JUNK — v*iich gets rids of useless segment subfiles created as a 
result of an aborted MPACK operation 

• NONE - which causes KIDDEL to display the "ZERO INDEXES" prompt: 
see below 

If you supply a list of valid index numbers to be deleted, optionally 
separated by commas, only these indexes will be deleted. KIDDEL then 
exits to PRIMOB. The space occupied by these segement subfiles will be 
reclaimed, and the deleted indexes will no longer exist. If you want 
them back, re-add them with the hDD option of CREATK (See Section 15) . 
Ihe numbers 18, 19, and 20 are not accepted as valid secondary index 
numbers. An index number of 0, representing the primary index, is not 
accepted either, for to delete the primary index implies deleting the 
entire file. Use the ALL option to delete the entire file. 
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Ihe JUNK option may be specified by itself or with the list of indexes. 
It will cause any useless segment subfiles created by an aborted MPACK 
operation to be deleted. KIDDEL will then exit to PRIMOS. 

ALL must be entered by itself and causes the entire MIDAS file to be 
deleted from the user's UFD. Again, KIDDEL will then exit to PRIMOS. 

The NONE option initiates the other KIDDEL dialog — the one that lets 
you initialize various parts of a MIDAS file so you can re-use part or 
all of the template. A NONE response is not the same thing as just a 
carriage return or blank line, both of v*iich cause the question to be 
re-asked . 

The "zero indexes" dialog begins with this question: 

ZERO INDEXES: 
ESiter one of the following in response to this prompt: 

• A list of indexes to be zeroed — the same rules as above apply. 
Indexes 18, 19, and 20 are not valid index numbers, and if you 
want to zero index 0, the primary index, use the "ALL" option. 

• ALL — will cause the entire MIDAS file consisting of the the 
primary index, the secondary index, and the pre-allocated 
records of a direct access file to be zeroed. Disk space is 
recovered by truncating the index levels back to just a root 
block, and deleting the resultant empty segment subfiles. Einpty 
data segment subfiles are also deleted, 

• NONE — will cause KIDDEL to exit to PRIMOS without doing 
anything to the file. 

Note that the "zero" operation will preserve the file read/write lock 
and non-standard segment subfile and segment directory lengths. In 
fact, if the user has specified the non-standard lengths with CREATK, 
but has yet to put them into effect by running MPACK, KIDDEL will 
effectively "MPACK" the indexes that is zeroes. Uhlike previous 
versions of KIDDEL, the current version will not continue if the user 
inputs a blank line or index numbers that don't exist, but instead will 
re-ask the last question until a suitable response is received. 
KIEOEL, like all the other major utilities, calls KX$RFC to verify that 
the user-specified filename is really that of a MIDAS file. 
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Changes to KBUILD 

The KBUILD utility has been re^written to provide for more flexibility, 
greater speed and accuracy and better error-checking. KBUILD' s dialog 
has changed slightly, so check out the dialog explanation in Section 3 
before using the new version. Other changes made to KBUILD are: 

• KBUILD now supports binary files written by FORTIWJ with the 
routine O$BD07, under the new "FTOBIN" file type. 

• E&cked decimal keys, and primary keys that don't start in the 
beginning of the data record are supported under the RPG file 
type. 

• The "CCeOL" file type accepted by KBUILD now works with 
uncompressed files: the "TEXT" file type should be used with 
compressed files. (Files that have been edited by the PRIMOS 
Elditor (ED) are compressed.) 

• KBUILD now builds MIDAS files with variable-length records. Ihe 
output file must have had variable-length records specified for 
it during CREATK. 

• When the user specifies an input file or files as being sorted, 
checking is now done to ensure that KBUILD will not attempt to 
build an index that already contains entries. 

• KBUILD will process secondary indexes that contain legal 
duplicate key values. 

• The error/logging milestones produced by KBUILD have been 
altered to deal with times that cross midnight. 

Changes to Internal Routines 

The routines affected by changes at Rev 17.6 are ERROHJ and KX$TIM. 
Although minor, the changes do require the user to alter existing 
programs that call them. 

Changes to ERROPN 

In previous version of MIDAS, if a blank line was supplied for a 
requested filename, ERROPN would fail. ERROPN now accepts a blank line 
as meaning no file is to be opened and thus informs the caller by 
returning an funit of 0. Another change to ERROPN is that the caller 
now receives "the"file unit that the error/logging file is opened on in 
the funit parameter, as opposed to supplying an actual file unit number 
on v*iich to open the error/logging file, as was the case in the past. 
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Changes to KX$TIM 

Ihe changes to KX$TIM involve both its function and its calling 
sequence . 

• KX$TIM now uses ERRFIL (in common area) as set up by ERROPN to 
figure out vdiere the error logging file is opened. Previously, 
there was a fourth argument located between v*at is now the 
first and second arguments that specified the file unit on viiich 
the error logging file was opened. 

• The numrec parameter, vAiich indicates the number of records to 
be processed for a particular milestone, has a new "special 
case" value. If set to -1, a milestone of with no header and 
without intialization, can be generated. 

• The counters have been enlarged and the computation of the 
elapsed time has been fixed to take into account a milestone 
interval that crosses midnight. 

See Section 14 for KX$TIM's calling sequence and an explantion of its 
purpose. 



Additions to PARM.K 

Ihe MIDAS parameter file that contains all the keys, variables etc. 
used by the FORTRAN subroutines in MIDAS is PARM.K. It is copied to 
the system UFD SYSCOM v^ien MIDAS is installed. Ihere are several new 
parameters in this file as of Rev. 17.6. They are: M$DACC, M$NRNW, 
M$NR1W, M$DLNG, M$DUPP, M$BIT, M$BYrE, M$WCM), M$BSTR, M$SPFP, M$DPFP, 
M$SINT, M$LINT, M$ASTR, ME$MF, ME$BAS, ME$BDS, ME$BKS, ME$BKT, ME$BL1, 
ME$BL2, ME$BLL, ME$CBD, and ME$NDA. They are used mainly by the 
offline routines documented in Section 14. 



NEW MIDAS RCXJTINES 

The new version of MIDAS contains several routines never before made 
available to users. Two of these will be of interest only to people 
that like using offline routines rather than the standard MIDAS 
utilities to do their template creation and file building. The others 
will be of immediate interest to all FORTRAN and PMA users, as they are 
integral to the operation of the concurrency handler. 



New Internal Routines 

At rev 17.6, twD routines KX$CRE and KX$RFC have been added that allow 
users to create and read the configuration of MIDAS files from 
programs. KX$RPC is called by most of the utilities to find out 
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vAiether the file is compatible with the current version of MIDAS, and 
to discern its configuration. KX$CRE is actually part of the CREATK 
utility vAiich is called by that utility to set up a MIDAS file 
template. Both of these routines are documented in Section 14. 



Itew File I/O Ftoutines 

FORTRAN and FMA users will need to use either OPEm$ and CLOSM$ to open 
and close their MIDAS files, or they can keep their old programs as is 
as long as they insert calls to NTFW$ before and after they process a 
MIDAS file. Ihese three routines were released at Rev 17.2, but some 
users may not have found out about them yet. See Section 6 for details 
on how to use them. 



New Install File 

The C_INSTALIMIDAS command file is new at Itev 17.6. It installs MIDAS 
by copying various files and command files to the UFD SYSTEM. It also 
copies the MIDAS libraries to the system UFD LIB, and copies all the 
parameter files to the system UFD SYSCOM, and copies all the MIDAS 
utilities (except REVERT and REMAKE) from MIDAS>CMDNC0 to the system 
UFD QWtiCe. 
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